Kit MCP Server & CLI

What is the Kit MCP server & CLI?

The Kit MCP server & CLI is a free, open source program that lets AI agents work with email newsletters, subscribers and automation through Kit’s documented API for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call directly to Kit’s API v4.

The CLI is the same program as commands. kit-cli list-broadcasts runs the same code your AI runs when you ask for your recent newsletters, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Show my latest five broadcasts and their statistics.
Draft my next newsletter privately and leave it unscheduled.
Find this subscriber by exact email and show their tags.
Add this subscriber to the requested tag after I confirm.
List my sequences and their emails.
Show account growth without changing anything.
Inspect my signed webhook endpoints.

Kit already offers an official hosted account MCP with reads and writes across API v4. This package adds a standalone task CLI and local desktop/account setup. It does not claim more API coverage or measured token savings over Kit’s server.

How to install the Kit MCP server

Choose your AI client in the install box. The npm package contains the MCP and CLI binaries; the versioned desktop bundle is attached to the GitHub release. Keep account credentials in private local settings.

Set up your private Kit account

Personal v4 API key

Open Kit's Developer settings, click Add a new key, name it and save the value privately when shown. Kit does not let you view that value again afterwards. Set KIT_API_KEY in your local shell or client settings. The server sends it in X-Kit-Api-Key, never a URL query string. Old v3 API secrets are not interchangeable.

Kit documents 120 requests over a rolling 60 seconds per API key and 600 for OAuth API access. The official hosted MCP separately documents 120/minute per token. This wrapper spaces calls per account by 550 ms for keys and 110 ms for OAuth. Other processes using the same credential also count against Kit's limits.

OAuth for full endpoint eligibility

Bulk and purchase endpoints in the tool table are marked OAuth-only. Create your own Kit app and enable API access, then implement the official OAuth authorization flow or Kit's Node example. Keep the app's secret on a private confidential backend. Use the callback URI exactly as registered, a cryptographically random state verified on callback, and HTTPS for a hosted callback.

The current authorization and token endpoints are https://api.kit.com/v4/oauth/authorize and https://api.kit.com/v4/oauth/token. There is no built-in OAuth consent service in this package. The old source's app.kit.com/oauth/token examples are obsolete. Follow Kit's current registered-app instructions; do not invent unsupported fine-grained OAuth scopes from operation-schema security labels.

A private token file can contain:

{
  "access_token": "YOUR_OAUTH_ACCESS_TOKEN",
  "refresh_token": "YOUR_OAUTH_REFRESH_TOKEN",
  "client_id": "YOUR_OWN_KIT_APP_CLIENT_ID",
  "client_secret": "YOUR_OWN_KIT_APP_CLIENT_SECRET",
  "created_at": 1790899200,
  "expires_in": 7200
}

These are placeholders; use actual issued expiry metadata. Point KIT_TOKENS_FILE at an absolute private path outside the checkout. It must be a regular JSON file, at most 64 KB; symlinks are refused. Restrict access to your OS user. If expiry metadata is available, refresh happens one minute before expiry. Concurrent refreshes within the same process are deduplicated. Updated tokens are written atomically with mode 0600. On Windows, protect the enclosing folder using user-only ACLs; POSIX mode bits are not a complete Windows access policy.

Alternatively set KIT_ACCESS_TOKEN, KIT_REFRESH_TOKEN, KIT_CLIENT_ID and KIT_CLIENT_SECRET privately. Without a token file, refresh state lasts only in that process. Without refresh credentials, renew an expired access token yourself. An OAuth access token takes precedence over an API key for the selected account.

Check that it works

Local doctor checks configuration. The network check reads the default account without returning its private details or sending email.

npx -y @thenavidm/kit-mcp-cli@latest doctor --network

A successful account read does not prove every endpoint’s plan/OAuth permissions, template compatibility or actual email delivery. Live account testing of this version remains pending.

Use the Kit CLI

The CLI is the same 85 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so list_broadcasts runs as kit-cli list-broadcasts.

npm install -g @thenavidm/kit-mcp-cli@latest
kit-cli --version
kit-cli
kit-cli list-broadcasts --help
kit-cli schema create-broadcast
kit-cli list-broadcasts --per-page 5 --agent --select broadcasts.id,broadcasts.subject,pagination
kit-cli get-broadcast-stats --broadcast-id 123 --agent

The bare kit-cli lists every command, and kit-cli <command> --help shows what a command takes. The 40 audience, delivery, deletion and signing-secret operations require --confirm. --agent and --yes never authorize a write. Tagging or form/sequence enrollment can trigger existing automations.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both surfaces call the same server tools. MCP connects them directly to an AI chat; the CLI gives an agent with a terminal the same operations as commands.

The token comparison is pending. We measure four real Claude Code usage differences: every tool loaded, default tool search, the skill read once, and its recurring description line. Commands, help, selected schemas, results and reasoning also contribute to complete task cost.

There is no measured efficiency percentage for this version yet. Standing context and the total cost of a successful task will be reported separately.

Draft, review and schedule

Draft privately, review, then schedule

A create call defaults to public:false and send_at:null. It creates a private unscheduled draft. It still requires confirmation because it changes account content and can accept delivery fields when explicitly supplied.

kit-cli list-email-templates --agent
kit-cli create-broadcast --subject "This week's creator notes" --content '<p>Write the actual newsletter here.</p>' --confirm --agent --select broadcast.id,broadcast.subject,broadcast.send_at
kit-cli get-broadcast --broadcast-id BROADCAST_ID_FROM_RESULT --agent

Positive IDs are returned by Kit; replace illustrative markers with real IDs. For an existing draft, validate the intended audience and delivery time before the separate confirmed update:

kit-cli update-broadcast --broadcast-id 123 --payload-file /absolute/private/path/schedule.json --confirm --agent

Your private schedule.json contains the ISO timestamp and the audience fields from the current schema, for example send_at with a timezone offset or UTC Z. published_at controls web publication metadata; it is not the email send time. Neither successful creation nor a local confirmation proves delivery. Read the broadcast and statistics afterwards.

Template HTML needs care

The API's content is HTML; it is not Kit's visual editor block tree. Preserve the full email wrapper and required Liquid unsubscribe/address markup when replacing content. Retrieve an existing example and inspect the selected template before updating. Do not replace a whole template with one paragraph if you need its existing branding and legal footer.

Kit's current OpenAPI prose contradicts itself around Starting point templates and required fields. This wrapper accepts a subject plus either content or email_template_id, allows nonempty partial broadcast updates, and exposes the documented allow_starting_point flag. These reviewed corrections are recorded with the snapshot. Starting point behavior remains unverified against a live account, so test with a private unscheduled draft and inspect it in Kit before any send.

Existing broadcasts and click reports

kit-cli list-broadcasts --per-page 10 --agent --select broadcasts.id,broadcasts.subject,pagination
kit-cli get-broadcast-stats --broadcast-id 123 --agent
kit-cli get-broadcast-clicks --broadcast-id 123 --agent

The client does not automatically retry POST, PUT, PATCH or DELETE requests. A timeout can have an unknown outcome. Check the existing draft or scheduled broadcast before repeating a write; sending twice cannot be undone by a retry wrapper.

Subscribers and sequences

Find an exact email or read a bounded list, then choose a requested audience change:

kit-cli search-subscribers --email-address reader@example.com --agent
kit-cli list-tags --agent
kit-cli tag-subscriber --tag-id 123 --email-address reader@example.com --confirm --agent
kit-cli list-subscriber-tags --subscriber-id 456 --agent

The .example address is illustrative. Do not add or tag real people without the requested account action. Tagging and form/sequence enrollment may trigger existing Kit automations.

filter_subscribers is a read-only POST with nested all/any filters. Use its current schema and a private JSON body; it is not a v3 page-number endpoint. search_subscribers is an exact-email compatibility alias, not a fuzzy search engine.

Sequences now have their own create/update/delete endpoints and individual email operations. Read their schemas and current delay units before using them. Sequence enrollment can deliver email through existing automation, so it is confirmed even if the API call itself merely adds a subscriber.

Custom field and tag creation are reversible configuration writes, so they do not require --confirm; they still disappear in read-only mode. Deletions, audience changes, snippets that can affect email and purchases are guarded. The tool table labels every operation.

Cursors and bulk work

Cursor pages

Kit v4 uses after, before, start_cursor and end_cursor, not old v3 numeric page arguments. Default per_page is 500, maximum 1000. Ask for a small page when you only need a sample:

kit-cli list-subscribers --per-page 25 --include-total-count --agent
kit-cli list-subscribers --after END_CURSOR_FROM_RESULT --per-page 25 --agent
kit-cli list-subscribers --all-pages --max-items 1000 --agent

Do not supply both before and after. all_pages traverses forward and refuses before. It stops at max_items (default 1000, maximum 10000) or 100 pages, and refuses repeated cursors. It reduces each page size to the remaining cap so the returned end cursor does not skip unseen records. Aggregated output includes collected, pages, the last pagination object and truncated.

include_total_count must be requested where supported; total count can add API work. max_items without all_pages is a usage error. This is bounded retrieval, not a backup/export guarantee for an entire large account.

OAuth-only bulk

The full API snapshot supplies nested request schemas and endpoint-specific limits. Discover the body and put private batches outside the checkout:

kit-cli schema bulk-create-subscribers
kit-cli bulk-create-subscribers --payload-file /absolute/private/path/subscribers.json --confirm --agent

Some bulk operations require a callback URL. Use HTTPS on a receiver you control and inspect its actual completion notification. The wrapper does not deploy or listen for callbacks. Split payloads according to Kit's current per-endpoint limits and the local 5 MB request cap. Do not retry an asynchronous submission merely because its completion has not arrived yet.

Signed webhook endpoints

The current signed webhook_endpoints family and older webhooks are separate APIs. Prefer signed endpoints for new setups. Discover the accepted event enum from the current schema:

kit-cli schema create-webhook-endpoint
kit-cli create-webhook-endpoint --url https://your-receiver.example/kit --events EVENT_FROM_SCHEMA --secret-name newsletter-hook --confirm --agent

Replace both placeholders with your own endpoint and a supported event. Creation and secret rotation require a new secret_name. Before the remote call, the server reserves that filename exclusively under KIT_PRIVATE_DIR (default ~/.config/kit-mcp-cli/secrets) with mode 0600. Existing files are never overwritten.

Returned signing secrets are redacted from model/CLI output and saved to the private file. The result exposes secret_file, not the secret itself. Configure your own receiver's signature verification privately. The package does not provide a receiver or claim that the endpoint is reachable. Protect private folders with Windows ACLs where applicable.

When rotating, update and verify your receiver before revoking the previous secret. If Kit changed the endpoint but local secret storage failed, inspect the remote endpoint before attempting rotation again. Do not paste signing secrets in an AI chat or public issue.

Official and community alternatives

COMPARISON.md records dated primary sources, scope and limitations. Counts are package discovery results, not evidence that the official server has fewer endpoints. No competitor latency, success rate or total token cost has been measured here.

Every Kit tool

All 85 tools, grouped the way the repo groups them. 38 only read, and 47 change something in your Kit account.

Account

Newsletters and statistics

Custom fields

Email templates

Forms

Published posts

Purchases (OAuth)

Segments

Sequence emails

Sequences

Reusable snippets

Subscribers

Tags

Signed webhook endpoints

Legacy webhooks

Is the Kit MCP server safe?

38 tools read data and 47 write. 40 guarded audience/delivery/deletion/secret operations require confirmation. Seven reversible configuration writes remain ordinary writes.

Draft creation defaults private and unscheduled. There are zero automatic retries for mutating calls, even after rate limits or timeouts. Inspect account state before repeating a write with an unknown outcome.

Make it read-only

Set KIT_READ_ONLY=1 to hide and refuse all 47 writes, leaving 38 reads. KIT_ALLOW_DESTRUCTIVE=0 separately blocks the 40 guarded operations even when confirmed. Reconnect after changing settings.

Keep a log of every write

Set KIT_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

Requests go directly to Kit, without a Navid-hosted relay or telemetry. Keys/OAuth client secrets remain in local private settings. OAuth refresh can update a regular private token file atomically with mode 0600. Signed webhook secrets go to exclusive private files and are redacted from model output. Optional guard logs contain tool/risk/surface/decision without arguments, account labels or credentials. Protect Windows files with user-only ACLs. Your AI client and Kit apply their own processing and retention policies.

Multiple private accounts

Set KIT_ACCOUNTS to a private JSON array. Its supported keys are name, api_key, access_token, refresh_token, client_id, client_secret and tokens_file. It replaces the single-account variables:

[
  {"name":"work","api_key":"YOUR_WORK_V4_KEY"},
  {"name":"personal","tokens_file":"/absolute/private/path/personal-kit.json"}
]

Set KIT_DEFAULT_ACCOUNT=work, then:

kit-cli list-accounts --agent
kit-cli list-broadcasts --account work --per-page 10 --agent
kit-cli get-growth-stats --account personal --agent

Names must be unique. list_accounts exposes labels, default choice and auth type only, never credentials or file paths. Guard logs omit account names. Separate processes are still preferable when you need strict account isolation.

Kit MCP server settings

Every setting comes from private shell or client environment. The package does not automatically load .env. GUI clients may not inherit terminal values.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

Complete client and desktop setup

INSTALL.md covers macOS, Windows and Linux, Claude Code, Codex, desktop extension/manual config, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, local Cline-style clients and Docker. It includes private credential routes, OAuth prerequisites, verification and removal. The local stdio server is not an HTTPS web connector; Kit’s official remote MCP is the suitable alternative for a remote-only client.

Let your AI guide setup
Help me install Kit MCP Server & CLI using INSTALL.md. Check Node and the binary, let me configure my account credentials privately, then run discovery and doctor --network. Do not send email or change subscribers during setup.

The npm package includes SKILL.md. Make it available through your agent’s supported skills location; installing npm does not automatically register it. Discovery and schemas work without credentials.

Desktop bundle

Download kit-2.0.2.mcpb from GitHub Releases and install it through Claude Desktop’s supported custom-extension settings. Enter a sensitive v4 key or an absolute private authorized OAuth token-file path. Enable read-only for the 38 reads. The archive includes production dependencies and no credentials. Its manifest requires a compatible Node runtime; a real GUI install remains a separate check. Manually installed archives need the new release installed to update them.

JSON bodies, null and output

Every command derives its arguments from the MCP schema. Use --help and schema before building a body. Path and query flags stay separate; body flags and payload/payload_file cannot be mixed. Array flags repeat once per item. JSON null must be passed inside payload, not as the shell string null.

kit-cli update-broadcast --broadcast-id 123 --payload '{"send_at":null}' --confirm --agent
kit-cli list-subscribers --include tags --include stats --per-page 10 --agent

These IDs are illustrative. --select shapes model output without changing what Kit sends to the server. Keep subscriber and email data out of public troubleshooting transcripts.

Versions, tags and updates

Version 2.0.2 has 85 tools: 83 operations from the pinned October 2 API snapshot, plus local account selection and an exact-email search alias. CHANGELOG.md records the major migration and dated validation. GitHub annotated tags, releases and desktop archives track the npm version. The repository uses 20 platform/surface topics and the package carries 30 relevant npm keywords.

Private legacy account instructions and history stay private. Browser login and designed broadcast/visual-automation duplication helpers are not included; use Kit UI for those workflows. New API sequence/email CRUD is separate from browser feature parity. Replace v3 credentials and numeric pages with v4 keys/OAuth and cursor pagination.

npm install -g @thenavidm/kit-mcp-cli@latest
kit-cli --version

Restart an @latest MCP connection to pick up updates. Pinned versions stay pinned. Remove CLI with npm uninstall -g @thenavidm/kit-mcp-cli and remove MCP/desktop entries separately. Uninstallation does not revoke Kit credentials, unschedule newsletters or remove local private token/secret files.

Validation and remaining evidence

Build, typecheck and 40 behavior/CLI checks passed. Real local stdio discovery confirms the counts and read-only behavior. The production audit has zero findings; SECURITY.md records a dev-only MCPB/node-forge advisory excluded from production artifacts. Release artifact/source/history checks are recorded in the repository as they complete.

Live authorized Kit calls, Starting point templates, actual desktop GUI installation and the fresh standing-context/matched-task token comparison remain pending. No fabricated token figures or superiority percentages are claimed.