AgentMail MCP Server Tools

0.2.2 verified Sat Apr 25 auth: no javascript

The `agentmail-mcp` package provides the Message Control Protocol (MCP) server, offering command-line tools for interacting with the AgentMail API. It enables users to expose AgentMail functionalities, such as sending, receiving, and replying to messages, as tools accessible by other applications or AI agents. Currently at version 0.2.2, this package is in an early development phase, likely receiving updates as the AgentMail platform evolves. Its core differentiator is simplifying the integration of AgentMail's messaging capabilities into automated workflows or agent-based systems by abstracting API calls into runnable commands. The release cadence is probably tied to AgentMail platform updates rather than a fixed schedule. It serves as a bridge, allowing external systems to leverage AgentMail's messaging features without complex direct API integrations.

Common errors

error Error: AGENTMAIL_API_KEY is not set. Please provide your AgentMail API key. ↓

cause The required `AGENTMAIL_API_KEY` environment variable was not supplied when invoking `agentmail-mcp`.

fix

Set the environment variable before running the command: AGENTMAIL_API_KEY="YOUR_API_KEY" npx agentmail-mcp ...

error Error: Invalid tool name 'typo_in_tool'. Available tools are: get_message, send_message... ↓

cause One or more tool names provided to the `--tools` argument do not match the expected names.

fix

Check the spelling and case of the tool names. Use a comma-separated list of valid tool names, for example: --tools get_message,send_message.

Warnings

breaking As a package in early development (version 0.x.y), its API, command-line arguments, and available tools are subject to frequent breaking changes without adhering strictly to semantic versioning. Always consult the latest README. ↓

fix Pin to exact versions in production environments and thoroughly test updates. Monitor the GitHub repository for release notes.

gotcha The `AGENTMAIL_API_KEY` is crucial for authentication. Failing to set it correctly as an environment variable will prevent the server from functioning. Do not hardcode API keys directly in source code. ↓

fix Always set `AGENTMAIL_API_KEY` as an environment variable (e.g., `export AGENTMAIL_API_KEY=...` or use a `.env` file) before running the `npx agentmail-mcp` command.

gotcha Tool names specified with `--tools` must exactly match the available tools provided by the AgentMail API. Supplying incorrect or misspelled tool names will result in those tools not being loaded or errors during runtime. ↓

fix Refer to the AgentMail API documentation or the `agentmail-mcp` source (if available) for the exact list of supported tool names. Ensure they are comma-separated without extra spaces.

Install

npm install agentmail-mcp

yarn add agentmail-mcp

pnpm add agentmail-mcp

Imports

agentmail-mcp (CLI invocation)
```
npx agentmail-mcp --tools get_message,send_message
```
This package is primarily designed as a command-line utility, executed via `npx` to spawn the MCP server. Its main functionality is accessed through command-line arguments and environment variables.
AgentMail API Key (Environment variable)
wrong
```
import { setApiKey } from 'agentmail-mcp'
```
correct
```
export AGENTMAIL_API_KEY="YOUR_API_KEY_HERE"
```
The API key for authentication is passed via the `AGENTMAIL_API_KEY` environment variable, not set programmatically through a library export.

Programmatic Import (CommonJS/ESM)

wrong

const mcp = require('agentmail-mcp');
// OR
import agentmailMcp from 'agentmail-mcp';

correct

Internal server error