home / mcp / inbound mcp server

Inbound MCP Server

Provides an MCP server to give your AI agent its own email mailbox for sending, receiving, and managing emails.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "inboundemail-mcp": {
      "url": "http://localhost:5454/mcp",
      "headers": {
        "INBOUND_DOMAIN": "yourdomain.com",
        "INBOUND_API_KEY": "YOUR_API_KEY",
        "INBOUND_MAILBOX": "Agent <[email protected]>"
      }
    }
  }
}

You can give an AI agent its own email identity and let it send, receive, and manage messages using this MCP server. It connects your agent to an email-based workflow so the agent can read, reply, and compose emails as if it were a real mailbox.

How to use

To work with an MCP client, point the client at the inbound MCP server and provide your API key and the mailbox you want the agent to use. You can run the server locally or connect to it over HTTP, then perform common mailbox and email operations from your agent.

Key workflows you can perform include checking for new messages in the mailbox, reading email details, replying to threads, and sending new emails from the agent’s mailbox. When sending, the agent’s display name appears as the sender so recipients recognize who is emailing them.

Important note: you must supply an API key and a mailbox address (with or without a display name) in the client configuration. The mailbox is the agent’s email identity used for all outgoing messages.

How to install

# Install via npm
npm install @inbound/mcp

# Or using pnpm
pnpm add @inbound/mcp

# Or using bun
bun add @inbound/mcp

Configuration

Configure the MCP server as either an HTTP endpoint or a local, STDIO-based process. You can use both methods if you want different clients or development setups to connect in parallel.

{
  "mcpServers": {
    "inbound": {
      "url": "http://localhost:5454/mcp",
      "headers": {
        "x-inbound-api-key": "your-api-key",
        "x-inbound-mailbox": "Support Agent <[email protected]>"
      }
    }
  }
}

HTTP and STDIO configurations

Use an HTTP-based connection for remote MCP servers and a local STDIO-based process when you want to run the MCP server directly in your environment.

# HTTP (remote or local HTTP gateway)
{
  "type": "http",
  "name": "inbound",
  "url": "http://localhost:5454/mcp",
  "args": [],
  "headers": {
    "x-inbound-api-key": "your-api-key",
    "x-inbound-mailbox": "Support Agent <[email protected]>"
  }
}
```
```json
# STDIO (local process via npx)
{
  "type": "stdio",
  "name": "inbound",
  "command": "npx",
  "args": ["-y", "@inbound/mcp"],
  "env": [
    {"name": "INBOUND_API_KEY", "value": "your-api-key"},
    {"name": "INBOUND_MAILBOX", "value": "Agent <[email protected]>"}
  ]
}

Security and authentication

The MCP server authenticates requests using your Inbound API key. Supply this key via an environment variable or an HTTP header depending on how you connect.

Optional domain restriction lets you limit operations to a single domain if needed. This can be configured via environment variables or HTTP headers depending on your setup.

Available prompts

getting-started is available to help you learn how to use the Inbound Email API effectively.

Development

Install dependencies, run in development mode, and build for production as you iteratively develop your MCP client integrations.

Available tools

check_mailbox

Check incoming emails for your mailbox (defaults to unread)

get_mailbox_threads

Get conversation threads where your mailbox is a participant

send_from_mailbox

Send emails from your mailbox with the sender automatically set

reply_from_mailbox

Reply to emails or threads from your mailbox with the sender automatically set

list_emails

List sent, received, and scheduled emails

get_email

Get detailed information about a specific email

send_email

Send or schedule an email

reply_email

Reply to an email or thread

retry_email

Retry delivery of a failed email

list_threads

List email conversations

get_thread

Get all messages in a thread

list_domains

List all domains in your account

list_endpoints

List webhook and email forwarding endpoints

create_endpoint

Create a webhook, email forward, or email group endpoint