agentmail-mcp

library0.3.0jsnpmunverified

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.

llm-agents communication http-networking

npm install agentmail-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AGENTMAIL-MCP

agentmail-mcp

llm-agentsjavascriptv0.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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)

✓ export AGENTMAIL_API_KEY="YOUR_API_KEY_HERE"

✗ import { setApiKey } from 'agentmail-mcp'

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)

✓

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

Attempting to `require()` or `import` this package for programmatic library use is discouraged as its primary interface is the command line. The package's internal API is not exposed for stable, direct programmatic consumption.

Demonstrates how to run the AgentMail MCP server as a command-line tool using `npx`, enabling specific AgentMail tools and passing the API key via an environment variable.

// To run the AgentMail MCP server with selected tools from your terminal: // Make sure to replace YOUR_AGENTMAIL_API_KEY with your actual key. const AGENTMAIL_API_KEY = process.env.AGENTMAIL_API_KEY ?? 'YOUR_AGENTMAIL_API_KEY'; if (AGENTMAIL_API_KEY === 'YOUR_AGENTMAIL_API_KEY') { console.error('Error: AGENTMAIL_API_KEY environment variable is not set. Please set your AgentMail API key.'); process.exit(1); } // Example using the shell command: console.log('Execute this command in your terminal:'); console.log(`AGENTMAIL_API_KEY="${AGENTMAIL_API_KEY}" npx -y agentmail-mcp --tools get_message,send_message,reply_to_message`); // For integration into a system that consumes a JSON configuration (as shown in README): const mcpConfiguration = { "mcpServers": { "AgentMail": { "command": "npx", "args": ["-y", "agentmail-mcp", "--tools", "get_message,send_message,reply_to_message"], "env": { "AGENTMAIL_API_KEY": AGENTMAIL_API_KEY } } } }; console.log('\nOr, for integration with a system that uses a structured configuration:'); console.log(JSON.stringify(mcpConfiguration, null, 2));

agentmail-mcp --version

Debug

Known issues

breakingAs 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.

affects: >=0.0.1

gotchaThe `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.

affects: >=0.0.1

gotchaTool 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.

affects: >=0.0.1

Errors

Common errors & fixes

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

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: Invalid tool name 'typo_in_tool'. Available tools are: get_message, send_message...

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`.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

64 hits · last 30 days

node

OpenAI (training)

Perplexity

Resources

githubhttps://github.com/agentmail-to/agentmail-mcp ↗

packagehttps://www.npmjs.com/package/agentmail-mcp ↗

homepagehttps://agentmail.to ↗