@letterapp/mcp

Letter MCP server — a Model Context Protocol server that gives your AI coding agent tools to set up and verify a Letter integration.

Built for AI coding agents (Claude Code, Cursor, Codex, Windsurf, Cline, OpenClaw). It reads the credential written by @letterapp/cli (~/.letter/credentials.json), so your MCP config never contains a secret and the key never appears in chat.

Installation

No install needed - your MCP client launches it on demand with npx. Add it to your client config:

{
  "mcpServers": {
    "letter": { "command": "npx", "args": ["-y", "@letterapp/mcp"] }
  }
}

Or install globally:

npm install -g @letterapp/mcp

Setup

First authenticate once from your project (this is what writes the credential the server reads):

npx @letterapp/cli

What happens:

1. The CLI opens a browser to confirm a short code and pick the project to connect.
2. Letter mints a project API key and delivers it to the CLI over a secure back channel. The CLI writes LETTER_API_KEY to .env.local and stores a copy in ~/.letter/credentials.json.
3. This server resolves that credential automatically - no API key in your MCP config.

The API key is never printed to the terminal or chat. In CI you can instead set LETTER_API_KEY in the environment.

Tools

| Tool | Description | | --- | --- | | setup_guide | Returns Letter's current step-by-step integration guide (markdown an agent can follow). | | check_connection | Reports whether the connected project has received any contacts or events yet. | | send_test_event | Sends a test identify + track to prove the pipe works end to end. Optional userId / email. | | identify | Report a user to Letter (userId, optional email, traits). | | track | Report an event a user performed (userId, event, optional properties). |

When no credential is found, every tool returns a friendly "run npx @letterapp/cli first" message instead of failing.

Environment Variables

| Variable | Default | Purpose | | --- | --- | --- | | LETTER_API_KEY | (from credential file) | Overrides the stored credential (CI). | | LETTER_BASE_URL | https://api.letter.app | API origin for self-host / local dev. | | LETTER_DOCS_URL | https://letter.app | Docs origin used by setup_guide. |

Security

The server never receives or stores a raw key in its config. It resolves the credential from ~/.letter/credentials.json (written by the CLI's browser-approved device flow) or from LETTER_API_KEY in the environment. Secrets are never logged or echoed back through tool results. Treat .env.local and ~/.letter/credentials.json as secrets and keep them out of source control.

Project Structure

src/
├── index.ts         # MCP server entry — registers tools over stdio
└── credentials.ts   # Resolves the Letter credential (env or ~/.letter)
package.json
tsconfig.json
tsup.config.ts

Development

npm install      # install dependencies
npm run build    # bundle to dist/ with tsup
npm run dev      # watch mode
npm run typecheck

node dist/index.js   # run the server over stdio

See Also

• @letterapp/cli — connect your app to Letter in one command.
• @letterapp/node — Node.js SDK.

Links

• Website: letter.app
• npm: @letterapp/mcp
• GitHub: vincenzor/letter-mcp
• Issues: Report a bug

License

MIT