{
  "markdown": "# MinuteMail MCP Server\n\n[MinuteMail](https://minutemail.co) as MCP (Model Context Protocol) tools: let\nAI agents and MCP clients operate ephemeral mailboxes, emails, attachments,\ncustom domains, teams, and mock OAuth identities for testing email and auth\nflows.\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Docker](https://img.shields.io/docker/pulls/chrptvn/minutemail-mcp)](https://hub.docker.com/r/chrptvn/minutemail-mcp)\n[![smithery badge](https://smithery.ai/badge/minutemailco/minutemail)](https://smithery.ai/servers/minutemailco/minutemail)\n\n- **Endpoint:** `https://mcp.minutemail.co/mcp` (Streamable HTTP, protocol\n  revision `2025-06-18`)\n- **Auth:** your MinuteMail API key (`Bearer mmak_...`). The server is a\n  stateless proxy — it holds **no credentials**, sessions, or local storage of\n  its own; your key is forwarded verbatim to the MinuteMail API, where scopes\n  and quotas are enforced. All state (mailboxes, mails, identities) lives in\n  the MinuteMail platform behind it.\n- Also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io)\n  as `io.github.minutemailco/mcp-server` and on\n  [Smithery](https://smithery.ai/server/minutemailco/minutemail).\n\n## Get an API key\n\n1. Sign up at [minutemail.co](https://minutemail.co) (free during early access)\n2. Create an API key in the dashboard\n3. Configure your MCP client to send it as the `Authorization` header:\n\n   `Authorization: Bearer mmak_XXXXXXXX`\n\n## Connect your MCP client\n\n**Claude Code / Claude Desktop / Cursor / any Streamable HTTP client:**\n\n- URL: `https://mcp.minutemail.co/mcp`\n- Header: `Authorization: Bearer mmak_...`\n\n**Claude Code CLI:**\n\n```bash\nclaude mcp add --transport http minutemail https://mcp.minutemail.co/mcp \\\n  --header \"Authorization: Bearer mmak_XXXXXXXX\"\n```\n\n**Claude Desktop / clients with an `mcpServers` JSON config** (e.g.\n`claude_desktop_config.json` / `~/.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"minutemail\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.minutemail.co/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer mmak_XXXXXXXX\"\n      }\n    }\n  }\n}\n```\n\n> Some clients (older Claude Desktop builds) only support local `stdio`\n> servers in their JSON config. If yours rejects `type: \"http\"`, use the\n> built-in remote/connectors UI with the URL and header above, or run\n> [mcp-remote](https://github.com/georgzf/mcp-remote) as a stdio bridge:\n>\n> ```json\n> {\n>   \"mcpServers\": {\n>     \"minutemail\": {\n>       \"command\": \"npx\",\n>       \"args\": [\n>         \"mcp-remote\",\n>         \"https://mcp.minutemail.co/mcp\",\n>         \"--header\",\n>         \"Authorization: Bearer mmak_XXXXXXXX\"\n>       ]\n>     }\n>   }\n> }\n> ```\n\nFor a guided walkthrough, see the docs:\n[docs.minutemail.co/mcp/getting-started](https://docs.minutemail.co/mcp/getting-started).\n\n**Raw JSON-RPC (what the clients do under the hood):**\n\n```bash\ncurl -s https://mcp.minutemail.co/mcp \\\n  -H 'Authorization: Bearer mmak_XXXXXXXX' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\n       \"params\":{\"name\":\"mailboxes.create\",\"arguments\":{\"expiresIn\":30}}}'\n```\n\n## Tools (39)\n\nEvery tool maps 1:1 to a route of the MinuteMail API. All calls require the\nBearer API key; write operations require the matching scope (`mailboxes`,\n`domains`, `team`, `identities`).\n\n### Mailboxes (`mailboxes` scope)\n| Tool | Purpose |\n|---|---|\n| `mailboxes.list` | List active mailboxes (optional exact-address lookup) |\n| `mailboxes.create` | Create a mailbox (optional TTL, domain, recovery tag) |\n| `mailboxes.get` / `mailboxes.delete` | Fetch / delete one mailbox |\n| `mailboxes.delete_bulk` | Delete several mailboxes by ID |\n| `mails.list` / `mails.inject` | List mails / simulate an inbound email (multipart, with attachments) |\n| `mails.get` / `mails.delete` / `mails.delete_bulk` | Read / delete mails |\n| `attachments.list` / `attachments.add` / `attachments.get` / `attachments.delete` / `attachments.delete_bulk` | Attachment CRUD |\n\n### Archived mailboxes (`mailboxes` scope)\n`archived.list`, `archived.get`,\n`archived.delete`, `archived.reactivate`.\n\n### Custom domains (`domains` scope)\n`domains.list`, `domains.register`, `domains.verify`, `domains.delete`.\n\n### Team (`team` scope)\n`team.members.list`, `team.members.add`, `team.members.get`, `team.members.delete`,\n`team.invitations.create`, `team.invitations.list`, `team.invitations.delete`.\n\n### Mock identities & OAuth clients (`identities` scope)\n`identities.list`, `identities.create`, `identities.update`, `identities.get`,\n`identities.delete`, `oauth.clients.list`, `oauth.clients.create`,\n`oauth.clients.get`, `oauth.clients.delete`, `oauth.clients.rotate_secret`.\n`identities.update` patches profile fields, `isActive` (activate/deactivate),\n`emailVerified` (drives the `email_verified` claim), and custom `claims`\nmerged into issued ID tokens and userinfo responses.\n\nTool results are returned as MCP text content carrying the API's JSON\nresponse. Non-2xx responses become `isError: true` results with the HTTP\nstatus and body (401 invalid key, 403 scope/domain, 429 quota with remaining\ncount, 502 upstream down).\n\n## Typical agent workflow\n\n```\nmailboxes.create (expiresIn 30)\n        ↓\nyour app under test sends a verification email to the mailbox address\n        ↓\nmails.list → mails.get (extract the code / link)\n        ↓\nassert the flow completed — the mailbox expires on its own\n```\n\n## Self-hosting\n\nThe server is a single static Go binary in a scratch image (~7 MB):\n\n```bash\ndocker run -p 8080:8080 \\\n  -e API_BASE=https://api.minutemail.co \\\n  ghcr.io/minutemailco/mcp-server:latest\n# or from Docker Hub:\ndocker run -p 8080:8080 \\\n  -e API_BASE=https://api.minutemail.co \\\n  chrptvn/minutemail-mcp:latest\n```\n\nSelf-hosting still requires MinuteMail API keys — the server is a stateless\nproxy over the hosted API, not a standalone implementation. It keeps no\nsessions or local data; every mailbox, mail, and identity is stored by the\nMinuteMail API it forwards to.\n\n| Env var | Default | Purpose |\n|---------|---------|-------------|\n| `PORT` | `8080` | Listen port |\n| `API_BASE` | `http://api-gateway:80` | MinuteMail API base URL (use `https://api.minutemail.co` outside the cluster) |\n| `LOG_LEVEL` | `warn` | `debug`/`info`/`warn`/`error` |\n| `LOG_FORMAT` | `json` | `json`/`text` |\n| `PROFILE` | `dev` | Deployment profile label |\n\n`GET /health` for liveness; `GET /metrics` for Prometheus counters.\nAPI-key management is not exposed via MCP — manage keys from the web app.\n\n## Development\n\nGo 1.23, stdlib plus `prometheus/client_golang`.\n\n```bash\ngo test ./...     # unit tests\ngo vet ./...\ngo run .          # local server on :8080\n```\n\n## License\n\n[MIT](LICENSE) — © [MinuteMail.co](https://minutemail.co)\n",
  "bytes": 6799,
  "sha": "a20e1d104e51d50589daef110edf21fe39a4031a34c6b2cef522dac8b44c90ee",
  "repo_slug": "minutemailco/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_minutemailco_mcp_server_5481951c/readme"
}