MCP Server

@vorlek/email-mcp brings Vorlek's email tools and account-aware catalog discovery to Claude Desktop, Cline, Cursor, and any stdio Model Context Protocol client. It is stateless, reads only VORLEK_API_KEY, and calls api.vorlek.com.

npx --yes @vorlek/email-mcp@latest stdio · Node 20+ · catalog-aware npm

Quickstart

Add the same command to your MCP host and set exactly one environment variable: VORLEK_API_KEY.

Add this to claude_desktop_config.json, then restart Claude Desktop.

{
  "mcpServers": {
    "vorlek": {
      "command": "npx",
      "args": ["-y", "@vorlek/email-mcp@latest"],
      "env": {
        "VORLEK_API_KEY": "vk_live_..."
      }
    }
  }
}

Add this to cline_mcp_settings.json from Cline's MCP Servers config.

{
  "mcpServers": {
    "vorlek": {
      "command": "npx",
      "args": ["-y", "@vorlek/email-mcp@latest"],
      "env": {
        "VORLEK_API_KEY": "vk_live_..."
      }
    }
  }
}

Add this to ~/.cursor/mcp.json.

{
  "mcpServers": {
    "vorlek": {
      "command": "npx",
      "args": ["-y", "@vorlek/email-mcp@latest"],
      "env": {
        "VORLEK_API_KEY": "vk_live_..."
      }
    }
  }
}

Tool reference

get_catalog has no arguments. get_operation requires the request_id from a prior response meta.request_id. Every provider tool requires provider with sendgrid, mailchimp, or klaviyo and accepts optional detail with minimal, standard, or full. Provider support matches the REST API and SDKs.

Tool	Required arguments	Purpose
`get_catalog`	none	Discover account-aware provider/tool support, connection state, response detail support, and operation receipt lookup shape.
`get_operation`	`request_id`	Look up an operation receipt using `meta.request_id` from a prior Vorlek call.
`upsert_contact`	`provider`, `email`	Create or update a contact in the selected provider.
`get_contact`	`provider`, `email`	Read one contact by email for read-after-write verification.
`get_connection_status`	`provider`	Check whether the stored provider credential is active.
`send_transactional`	`provider`, `to`, `subject`	Send one transactional email. SendGrid is supported at launch.
`get_campaign_stats`	`provider`, `campaign_id`	Fetch normalized sent, open, click, bounce, and unsubscribe counts.
`list_templates`	`provider`	List templates with `limit`, `cursor`, and optional page-scoped `query` search.
`list_campaigns`	`provider`	List campaigns with optional `status`, `limit`, and `cursor`.

Success response shape

Successful tool calls return an MCP content block with a single text entry. The text is a JSON-encoded {data, meta} envelope mirroring the SDK contract — data is the normalized tool payload, meta carries the request id, quota state, rate-limit state, idempotency replay state, and response detail metadata when present.

{
  "content": [
    {
      "type": "text",
      "text": "{\"data\":{\"contact_id\":\"abc123\",\"action\":\"upserted\"},\"meta\":{\"request_id\":\"01HV...\",\"quota\":{\"used\":42,\"limit\":1000},\"ratelimit\":{\"remaining\":98},\"idempotency\":{\"replay\":false}}}"
    }
  ]
}

Available from v1.0.2 onward. Earlier 1.0.x releases returned only the data field; agents calling v1.0.1 will still see correct payloads but lose request_id and quota/rate-limit observability.

Error response shape

Expected Vorlek API failures return MCP tool errors with a JSON text body. Agents can inspect code, retry_safe, request_id, provider, and retry_after before deciding whether to retry or ask for configuration help.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"code\":\"RATE_LIMITED\",\"category\":\"client\",\"retry_safe\":true,\"request_id\":\"01HV...\",\"provider\":\"sendgrid\",\"retry_after\":30,\"message\":\"Rate limited.\"}"
    }
  ]
}

Troubleshoot

Symptom	Likely cause	Fix
`_unconfigured` appears	`VORLEK_API_KEY` is missing.	Add the env var to the MCP host config and restart the host.
`AUTH_INVALID`	The Vorlek key is invalid or revoked.	Create a fresh key at vorlek.com/keys.
`TOOL_NOT_SUPPORTED`	The provider/tool pair is not available.	Use SendGrid for transactional sends or choose a supported tool for the provider.
Server fails before tools load	Node.js is missing or too old.	Install Node 20+ and use `npx --yes @vorlek/email-mcp@latest`.

Cross-SDK parity

The MCP server shares the same request/response contract as the REST API and SDKs. MCP wraps each successful result as text JSON and maps expected VorlekError failures to structured isError responses instead of crashing the server.