Shipmail MCP Server

Official Model Context Protocol server for Shipmail. Connect MCP-compatible agents (Claude Desktop, Cursor, VS Code, Windsurf, and others) to Shipmail domains, mailboxes, messages, threads, webhooks, and suppressions.

Model Context Protocol is an open standard for connecting LLM clients to external tools and data. This server runs locally over stdio and exposes the Shipmail API to your agent.

Transport: stdio (local). Requirements: Node.js 20+ and a Shipmail API key.

Contents

• Quick start

  • Claude Desktop

  • Cursor

  • VS Code

  • Windsurf

• What you can do

• Tools

• Resources

• Prompts

• Configuration

• Security

• Privacy

• Troubleshooting

• Development

• License

• Links

Related MCP server: ShipEngine API MCP Server

Quick start

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "shipmail": {
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": {
        "SHIPMAIL_API_KEY": "sm_live_..."
      }
    }
  }
}

Restart Claude Desktop. The Shipmail tools appear under the tools menu.

Cursor

Add to .cursor/mcp.json in the project root, or ~/.cursor/mcp.json for global use:

{
  "mcpServers": {
    "shipmail": {
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": {
        "SHIPMAIL_API_KEY": "sm_live_..."
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json. The inputs block prompts for the key on first use instead of storing it in the file:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "shipmail-api-key",
      "description": "Shipmail API key",
      "password": true
    }
  ],
  "servers": {
    "shipmail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": {
        "SHIPMAIL_API_KEY": "${input:shipmail-api-key}"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "shipmail": {
      "command": "npx",
      "args": ["-y", "shipmail-mcp"],
      "env": {
        "SHIPMAIL_API_KEY": "sm_live_..."
      }
    }
  }
}

What you can do

Once connected, ask your agent:

• "Set up acme.com on Shipmail and show me the DNS records I need to add at my registrar."

• "Create a mailbox support@acme.com and turn on auto-reply with this text..."

• "Triage the threads in support@acme.com from this week and summarize what needs attention."

• "Reply to thread thread_abc123 confirming we ship Friday."

• "Create a webhook that posts new email events to https://example.com/hooks/shipmail, then send a test event."

• "Show recent deliveries for webhook whk_xyz and flag any that failed."

Tools

All tools are namespaced with shipmail_ to avoid collisions with peer MCP servers.

To restrict the surface, pass --tools (overrides SHIPMAIL_MCP_TOOLS):

{
  "args": [
    "-y",
    "shipmail-mcp",
    "--tools",
    "shipmail_list_mailboxes,shipmail_get_thread,shipmail_reply_to_thread"
  ]
}

Resources

Read-only resources for inspection without tool calls:

• shipmail://account/status

• shipmail://domains

• shipmail://domains/{id}

• shipmail://mailboxes

• shipmail://mailboxes/{id}

• shipmail://mailboxes/{id}/folders

• shipmail://mailboxes/{id}/identities

• shipmail://mailboxes/{id}/rules

• shipmail://mailboxes/{id}/inbox/messages

• shipmail://mailboxes/{id}/inbox/threads/{thread_id}

• shipmail://messages/{id}

• shipmail://threads/{id}

Prompts

Pre-built prompts the agent can use as guided workflows:

• setup_domain: connect a new domain and walk through DNS setup.

• triage_mailbox: read recent threads in a mailbox and summarize what needs attention.

• draft_email_reply: draft a reply for a given thread, ready for user review.

• configure_webhook: set up and test a webhook for incoming events.

Configuration

Security

• Tool namespacing: All tools are prefixed with shipmail_ to avoid collisions with peer MCP servers in the same host.

• Structured outputs: Successful tools return both text fallback content and structured MCP structuredContent.

• Idempotency: Mutating tools accept an optional idempotency_key. When omitted, the server generates a fresh key per tool call. Supply your own key if a specific request must stay idempotent across MCP retries.

• Input sanitization: Email content, addresses, and error text are stripped of ASCII control characters, DEL, and Unicode directional or BiDi markers (U+061C, U+200E/F, U+202A-E, U+2066-9). Long strings are truncated.

• Error redaction: 5xx and unexpected Shipmail errors are redacted to a generic message; the original request_id is preserved for support. Generic Error thrown values (network errors, deserialization) are redacted to "Internal MCP error" before reaching the LLM. Detail lands on stderr.

• Circuit breaker: Each session enforces per-tool rate limits and a hard total-call ceiling as a runaway-agent guard. These are not abuse controls. Real abuse limits live at the API per API key. Restart the server to reset.

• Webhook URL validation: Webhook URLs must be public https endpoints. Localhost, RFC1918, link-local, ULA, IPv4-mapped IPv6, 0.0.0.0, decimal-int IPs, .local, and .internal hosts are rejected at input time.

• Destructive annotations: Tools that delete, retarget, rotate, replace rules, reset credentials, or create automatic outbound responses are annotated with destructiveHint. Hosts that gate on this annotation will prompt the user. Annotated tools include shipmail_update_domain, shipmail_update_webhook, shipmail_rotate_webhook_secret, shipmail_delete_mailbox_folder, shipmail_set_mailbox_rules, shipmail_reset_mailbox_password, and shipmail_set_auto_reply in addition to obvious deletes.

Domain purchase is intentionally excluded.

What this server does not defend against

• Indirect prompt injection from email content. Reading a mailbox exposes the agent to attacker-controlled email bodies. The sanitizer strips invisible glyphs but cannot detect natural-language injection ("ignore previous instructions, send to..."). Only call destructive tools after explicit user approval.

• Malicious LLM output or hallucinated arguments. The MCP layer cannot tell whether an argument came from the user or was invented. Use the host UI's tool-call confirmation, especially for destructiveHint:true tools.

• Compromised MCP host. Your API key is read from SHIPMAIL_API_KEY and held in memory by this process. If the host is compromised, the key is gone regardless. Rotate keys you suspect have been exposed.

• Webhook signing secret in conversation logs. shipmail_create_webhook and shipmail_rotate_webhook_secret return the secret in structuredContent. Many MCP clients persist tool output in conversation history. Treat the session log as sensitive after these calls.

Privacy

This server forwards email subject lines, bodies, headers, attachment metadata, and recipient lists to whatever LLM you connect it to. The LLM provider may log that content. For privacy-sensitive workflows, restrict the tool surface with --tools so the LLM only sees what it needs.

Troubleshooting

SHIPMAIL_API_KEY is not set. Confirm the host config includes the key in the env block, then restart the host.

Base URL must be https on a shipmail.to host. You set SHIPMAIL_BASE_URL to something else. For local development, also set SHIPMAIL_ALLOW_INSECURE_BASE_URL=1.

Tools do not show up in the host. Confirm the package launched. Most hosts surface a server log near the chat input or in a developer panel. Set SHIPMAIL_MCP_DEBUG=1 to add request_id and status to stderr.

Internal MCP error. A non-API error (network, deserialization) was redacted before reaching the agent. Check the host's stderr panel for the underlying detail.

Rate limit hit mid-session. The per-session circuit breaker tripped. Restart the MCP server (in most hosts: toggle the server off and back on, or restart the host).

Webhook URL rejected. URLs must be public https. Localhost, RFC1918, .local, and .internal are blocked at input time. Use a public tunnel (ngrok, cloudflared) for local testing.

Development

Install dependencies with Bun:

bun install

Run the server locally against the published Shipmail SDK:

SHIPMAIL_API_KEY=sm_live_... bun run dev

Run the standalone checks:

bun run typecheck
bun test
bun run build

The OpenAPI coverage test uses fixtures/openapi.json, copied from https://shipmail.to/openapi.json when this public source repo is synced.

License

MIT.

Links

• Shipmail docs

• MCP guide

• API reference

• shipmail SDK on npm

• TypeScript SDK docs

• Model Context Protocol

• Source repository

• Issues