Mektup MCP Server

Mektup MCP Server

Mektup is a self-hosted, multi-domain email platform. This MCP server lets an AI coding agent (Claude Code, Claude Desktop, Cursor, Lovable, Replit, Base44, or any MCP-compatible client) manage real email for a domain — register it, add the DNS records, create mailboxes, send and read mail, manage drafts/contacts/folders/forwarding/vacation replies — as native tool calls inside its own session, instead of the human hand-writing curl commands or pasting an API key into generated code.

Every tool call is a straight HTTP call to the real Mektup REST API. There's no separate logic to learn — if you understand the API, you understand the MCP server. Full coverage: every REST endpoint has a matching tool, verified with real read and write round-trips against the live production API (create → update → list → delete, confirmed at each step).

Two ways to run it, same tool set either way (lib/build-server.js defines the tools once, shared by both):

• Remote (Streamable HTTP) — a server we host at https://mcp.usemektup.com/mcp. Point any client that takes a "custom MCP server" URL at it directly, no install. This is what Lovable/Cursor/Replit/Base44-style platforms want.
• Local (stdio) — run server.js yourself with your key in an env var. For MCP clients that only support launching a local process (Claude Desktop config, etc.).

---

Remote server (recommended for platform integrations)

Endpoint: https://mcp.usemektup.com/mcp (Streamable HTTP — supports both the direct-JSON-response and SSE-streaming response modes of the spec).

Stateless: no session is kept between requests — every tool call is already a one-shot passthrough to the REST API, so there's no session state worth keeping.

Tenant isolation: identical to the REST API, because it is the REST API underneath — the server holds no account-specific credential itself, it just forwards whichever token the caller sent (API key or OAuth access token, see below) straight through to api.usemektup.com, which is the only place that actually verifies it. A token only ever sees its own account's data.

Two auth modes, same endpoint, both arrive as the same Authorization: Bearer <token> header:

OAuth (recommended for platform integrations)

For a platform with real end users (Lovable, Cursor, Replit, Base44, ...) — the user clicks "connect," signs in with their existing Mektup account, approves, done. No token copy-paste, no dashboard visit.

Clerk (clerk.usemektup.com) is the OAuth 2.1 authorization server — this MCP server is only ever a resource server. Discovery is automatic for any spec-compliant OAuth-capable MCP client: it only needs the endpoint URL above and finds the rest itself via https://mcp.usemektup.com/.well-known/oauth-protected-resource/mcp (RFC 9728), which points at Clerk's own https://clerk.usemektup.com/.well-known/oauth-authorization-server (RFC 8414). From there the client registers itself via Dynamic Client Registration (no manual setup needed on your end) and runs a standard Authorization Code + PKCE flow, ending with a JWT access token used exactly like an API key.

Lovable: Connectors → All → Custom (MCP card) → Server Name Mektup, Server URL https://mcp.usemektup.com/mcp, Auth → OAuth (default when a server supports it) → Add & authorize.

API key (simplest for a single account, scripts, or a client without OAuth support)

Authorization: Bearer mek_live_... — create one at app.usemektup.com → API keys.

Adding it to a client that supports custom MCP connectors is normally 3 fields:

Cursor / Claude Desktop / any client that reads raw MCP JSON config:

{
  "mcpServers": {
    "mektup": {
      "url": "https://mcp.usemektup.com/mcp",
      "headers": { "Authorization": "Bearer mek_live_..." }
    }
  }
}

Replit / Base44 / other "connect a tool" flows: same three fields as the table above — server URL, Bearer auth, key.

---

Local (stdio) setup

Use this when a client can only launch a local process, not call a remote URL.

1. Get an API key. Sign in to the dashboard at app.usemektup.com, open API keys, and create one. Keys look like mek_live_... and are shown exactly once - copy it immediately.

2. Install dependencies:

git clone https://github.com/WeeCi/mektup-mcp.git
cd mektup-mcp
npm install

3. Configure your MCP client to run server.js with the key as an environment variable. For Claude Desktop / Claude Code, add to your MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "mektup": {
      "command": "node",
      "args": ["/absolute/path/to/mektup-mcp/server.js"],
      "env": {
        "MEKTUP_API_KEY": "mek_live_..."
      }
    }
  }
}

MEKTUP_API_BASE_URL is optional and defaults to https://api.usemektup.com — no need to set it under normal use.

The server refuses to start without MEKTUP_API_KEY set.

---

How tools respond

Every tool returns its result as JSON text on success. On failure, it returns isError: true with Error: <message> — the message is the same one the underlying REST endpoint returned (see the API reference for exact error conditions, including billing-limit 402s, per endpoint).

---

Tools

Account

API keys

Domains

Mailboxes

Forwarding

Identity

Vacation / auto-reply

Folders

Contacts

Account-level, not per-mailbox.

Drafts

Sending

Example:

send_email({ from: "hello@example.com", to: "you@gmail.com", subject: "It works", text: "Real mail, sent through Mektup." })
→ { "messageId": "<...@example.com>", "envelope": { "from": "hello@example.com", "to": ["you@gmail.com"] } }

Messages & threads

Account-wide

---

See also

• Full REST API reference — everything this server wraps
• OpenAPI 3.1 spec — machine-readable version of the same API
• usemektup.com — sign up, dashboard, pricing

License

MIT