Beehiiv MCP Server & CLI

What is the Beehiiv MCP server & CLI?

The Beehiiv MCP server & CLI is a free, open source program that lets AI agents work with newsletters, subscriber lists and account data through Beehiiv’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 Beehiiv API v2.

The CLI is the same program as commands. beehiiv-cli list-publications runs the same code your AI runs when you ask which publications your credentials can access, 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 the publications my credentials can access.
Summarize the latest five posts in the publication I choose.
Draft my next newsletter and leave it unscheduled.
Inspect that existing post ID and tell me if it is still processing.
Find this subscriber by exact email.
Show newsletter-list and automation membership before the audience change I requested.
Inspect my webhook endpoints without exposing signing secrets.

Beehiiv already has an official account MCP and a separate developer-docs MCP. A community Go task CLI also exists. This package adds local MCP and CLI access to the pinned API operations, private named accounts, bounded native cursor retrieval and explicit write controls. Official MCP UI coverage and API Send workflows differ; neither is declared universally better.

How to install the Beehiiv MCP server

Choose your client in the existing install box. One npm package contains MCP and CLI binaries, and the GitHub release supplies a desktop archive. Configure account access privately before a network read.

Set up your private Beehiiv account

API key for personal automation

1. Sign in to Beehiiv.
2. Open Settings > API under Workspace Settings.
3. Choose Create New API Key. Name the integration and restrict its publications where appropriate.
4. Save the newly shown key in private local settings. It cannot be viewed again after leaving the page.
5. Set BEEHIIV_API_KEY in the process/client that launches the package, then run doctor and a read.

Use the current key instructions. Keys use Bearer authentication. Requests to publications outside a restricted key's scope return 404, and workspace-wide data deletion returns 403. A password is not an API key. The package does not load .env files automatically. GUI clients may not inherit a terminal environment.

Your own OAuth integration

Register a client through Beehiiv support. Use your own client ID, exact registered callback, a verified random state and PKCE for public clients. Authorization uses https://app.beehiiv.com/oauth/authorize; exchange/refresh uses https://app.beehiiv.com/oauth/token with application/x-www-form-urlencoded. Confidential clients also supply their private client secret.

Request only the documented scopes needed by the user. The default identify:read scope does not authorize all account reads/writes. The tool catalog records upstream endpoint scope labels. The test-send endpoint is labeled only posts upstream; confirm its required granted action through current Beehiiv permissions rather than treating that label as an OAuth scope to request. identify_oauth_user requires an OAuth session. This package does not provide a hosted callback, borrow another CLI's OAuth app or implement the initial browser consent flow.

Save the authorized token response and your app settings to a private regular JSON file outside the repo:

{"access_token":"YOUR_ACCESS_TOKEN","refresh_token":"YOUR_REFRESH_TOKEN","client_id":"YOUR_OWN_APP_ID","client_secret":"YOUR_CONFIDENTIAL_APP_SECRET"}

Omit client_secret for a public client. Include the real issued created_at/expires_in metadata when available. Set BEEHIIV_TOKENS_FILE to the absolute path. Files must be regular, at most 64 KB; symlinks are refused. Protect POSIX files with mode 0600 and Windows folders with user-only ACLs. Refresh updates files atomically. Without a file, environment-based refreshed state lasts only in that process. OAuth access tokens take precedence over an API key.

Rate limits and disconnecting

Current API limits are Free 30, Lite 180, Pro 500 and Enterprise 800 requests/minute. The wrapper defaults to conservative 2,000 ms pacing per account. Configure a supported interval when your plan and shared credential traffic justify it. Other processes also count; a response header after an idle period alone is not a complete plan eligibility check.

Revoke the API key or authorized app in Beehiiv, remove private client settings and reconnect. Uninstalling the package does not revoke credentials, delete remote subscribers or unschedule posts.

Check that it works

Discovery and schemas work without credentials. The local doctor checks setup; the network doctor reads permitted publications without returning private publication content.

beehiiv-cli --version
beehiiv-cli doctor
beehiiv-cli doctor --network
beehiiv-cli list-publications --limit 1 --agent

A successful read establishes that credential’s access to the requested endpoint. It does not establish Send API, all OAuth scopes or every plan feature. Start with read-only and inspect discovery before authorizing changes.

Use the Beehiiv CLI

The CLI is the same 117 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_publications runs as beehiiv-cli list-publications.

npm install -g @thenavidm/beehiiv-mcp-cli@latest
beehiiv-cli
beehiiv-cli list-publications --help
beehiiv-cli schema create-post
beehiiv-cli list-posts --publication-id pub_00000000-0000-0000-0000-000000000000 --limit 5 --agent

The bare beehiiv-cli lists every command, and beehiiv-cli <command> --help shows what a command takes. Every mutation requires --confirm for the action the user requested. --agent, --yes and prior unrelated confirmation never authorize changes. The zero publication ID is illustrative; replace it with an ID from your account.

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.

Drafts, sending and subscriber workflows

Create a draft, then inspect the same post

The Send API requires eligible Pro/Enterprise access. Creation accepts a title and exactly one of blocks or body_content. Draft is the default; scheduling a draft is refused. These zero IDs are illustrative, not real account resources: replace them with IDs from Beehiiv before executing.

beehiiv-cli list-posts --publication-id pub_00000000-0000-0000-0000-000000000000 --limit 5 --agent
beehiiv-cli create-post --publication-id pub_00000000-0000-0000-0000-000000000000 --title "Creator notes" --body-content '<p>Your actual newsletter content.</p>' --confirm --agent
beehiiv-cli get-post --publication-id pub_00000000-0000-0000-0000-000000000000 --post-id post_00000000-0000-0000-0000-000000000000 --agent

Creation returns an accepted post ID before background processing is complete. The wrapper marks creation_pending. A subsequent HTTP 202 read returns pending state plus Retry-After when present; it does not poll forever or resubmit. Preserve the ID, wait as instructed and read it again. A POST_CREATION_FAILED 404 is a failure. Inspect account state before repeating an unknown write outcome.

Structured blocks, HTML and scheduling

Use beehiiv-cli schema create-post or schema update-post, then a private payload file for nested content. HTML uses inline CSS; style/link tags are stripped by Beehiiv. Template content and content_merge_strategy affect whether the template header/content is preserved. Inspect the rendered draft in Beehiiv before a confirmed scheduling/delivery update. Do not replace a branded template with one paragraph by accident.

An update needs a nonempty body, refuses both blocks and body_content, and validates the current documented fields. A schedule uses the appropriate confirmed status and scheduled_at fields. No local guard or HTTP acceptance establishes successful email delivery.

Subscribers and automations

Discover an existing subscriber and read the intended publication before applying an audience change. Create subscription can reactivate an existing record, send a welcome email, enroll automations or modify paid-tier associations when those fields are supplied. Every write requires confirmation; reading a list is not permission to send or reactivate.

Private podcast feeds, exported account data, billing/advertising-related offers and workspace privacy deletions need particular care. A tool's existence does not imply your key, plan or OAuth scopes permit it. Only perform the user-requested action.

Pagination, exports and webhooks

Native cursors and deprecated offset pages

Only 13 reviewed operations expose cursor. They accept all_pages and a max_items cap (default 1,000, maximum 10,000), stop after 100 pages and refuse repeated cursors. The last request size shrinks to the remaining cap so its next cursor does not skip unseen records. Aggregated output reports collected/pages/truncated plus the last pagination object.

Do not mix cursor with page, or all_pages with page. max_items without all_pages is refused. Offset-only tools, including the reviewed list_posts/list_publications schemas, retain deprecated page input capped at 100; they do not receive invented cursor support. The current pagination guide recommends cursor where available, with limit at most 100 and default 10.

beehiiv-cli list-subscriptions --publication-id pub_00000000-0000-0000-0000-000000000000 --limit 25 --agent
beehiiv-cli list-subscriptions --publication-id pub_00000000-0000-0000-0000-000000000000 --all-pages --max-items 500 --agent

Exports and asynchronous operations

A successful create/export response can mean work was accepted, not that every record is exported. Keep returned job/resource identifiers and inspect the appropriate existing resource. A bounded list is not a complete backup guarantee. Protect response data and download links as private account content.

Webhook receivers

Webhook management requires eligible Lite+ access and appropriate scopes. Create/update the requested endpoint through the API, then retrieve its signing secret privately from the endpoint UI and configure your own receiver. Verify Svix-style signature headers according to Beehiiv's current webhook documentation. This package does not deploy a receiver, prove public reachability or return a signing-secret file. Never paste a signing secret into model context.

Every Beehiiv tool

Actual discovery supplies all 117 tools below: 70 reads and 47 writes. Every write asks for confirmation. The complete argument tables and beehiiv-cli schema expose required IDs, nested bodies, scopes and native cursor controls. Tool counts do not imply complete UI feature parity.

Ad network offers

Ad network reports

Advertisement opportunities

Authors

Automation journeys

Automations

Bulk subscriptions

Bulk subscription updates

Subscriptions

Complimentary access

Condition sets

Custom fields

Data deletion

Engagements

Exports

Newsletter lists

Newsletter list subscriptions

Oauth users

Podcasts

Polls

Posts

Post templates

Publication fields

Publications

Referral program

Segments

Subscription tags

Tiers

Webhooks

Workspaces

Accounts

Is the Beehiiv MCP server safe?

All 47 mutations require explicit confirmation. Read-only removes them from discovery and refuses direct calls to them. BEEHIIV_ALLOW_DESTRUCTIVE=0 refuses writes even when confirmed.

Send, subscription changes, private-feed emails, ad acceptance, exports and privacy deletion can have materially different effects. Review the exact operation, account and publication. Mutations have zero automatic retries; after an unknown outcome inspect account state before repeating them.

Make it read-only

Privately set BEEHIIV_READ_ONLY=1, restart or reconnect and verify that discovery contains 70 reads. Remove or disable it only when you want the requested writes available. Every write still needs confirmation.

Keep a log of every write

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

Your data

API calls go directly to https://api.beehiiv.com/v2, with OAuth refresh at https://app.beehiiv.com/oauth/token. No Navid-hosted relay or telemetry is included. Redirects are refused. API keys, access/refresh tokens and client secrets are sanitized from results and reflected errors.

Subscriber addresses, newsletters, analytics, export links and private podcast URLs remain authorized private business data, not anonymized information. Your AI client and Beehiiv apply their own retention/sharing policies. Do not treat secret redaction as removal of all account data.

Private token files and optional guard logs stay on the server's machine. Refresh writes an owner-only temporary file and renames it atomically. Guard logs omit arguments, account labels and credentials; they record decisions and attempts, not proof of remote delivery. Logging failure does not block a requested operation. See SECURITY.md for disclosure and dependency limitations.

Several private accounts

Set BEEHIIV_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_API_KEY"},
  {"name":"personal","tokens_file":"/absolute/private/path/personal-beehiiv.json"}
]

Set BEEHIIV_DEFAULT_ACCOUNT=work, then:

beehiiv-cli list-accounts --agent
beehiiv-cli list-publications --account work --limit 10 --agent
beehiiv-cli list-publications --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.

Account selects credentials; publication_id selects a permitted publication. They are separate concepts. A restricted key can list only the publications in its scope.

Beehiiv MCP server settings

Set these in private local shell or client settings. GUI apps may not inherit your terminal environment; this package does not automatically load .env. Named account labels select credentials; publication IDs select remote resources.

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, OS and desktop setup

The following configurations use placeholders. Put actual values only into private user settings, outside repositories. INSTALL.md is included in the npm package and covers updating and removal. A browser-only remote client needs the official hosted MCP, because this package exposes local stdio.

Claude Code

For a user-scoped connection, after privately configuring credentials:

claude mcp add --scope user beehiiv -- npx -y @thenavidm/beehiiv-mcp-cli@latest
claude mcp list

Use the client's private local environment settings for the account variable if they are not inherited. Claude's -e NAME=value registration option writes values into its config; only use it locally through your secret manager, with no shared command transcript. Never place credentials in a project .mcp.json. Reconnect and ask Claude to verify credentials.

Alternatively install the CLI, make SKILL.md available to Claude, and use shell commands. Registering both surfaces is optional.

Codex

codex mcp add beehiiv -- npx -y @thenavidm/beehiiv-mcp-cli@latest
codex mcp list

Account credentials must reach the server through private environment settings. codex mcp add --env NAME=value stores values in your local config, so never commit that config or put secrets in a shared command. In TOML, the equivalent server is:

[mcp_servers.beehiiv]
command = "npx"
args = ["-y", "@thenavidm/beehiiv-mcp-cli@latest"]
env_vars = ["BEEHIIV_API_KEY", "BEEHIIV_TOKENS_FILE"]

env_vars forwards those names from the environment available to Codex. If that environment does not contain them, configure private env settings locally. Codex can also call the CLI directly with SKILL.md and --agent output.

Claude Desktop

Install the .mcpb extension

1. Download beehiiv-2.0.0.mcpb from GitHub Releases.
2. In a supported Claude Desktop build, open Settings > Extensions > Advanced settings > Install Extension… and select it.
3. Enter a private API key in the sensitive setting, or an absolute private OAuth token-file path. Leave the unused method empty.
4. Enable read-only if you want only the 70 reads. Reconnect and ask for account verification.

The bundle includes production dependencies and no credentials. Use the token-file route for your own authorized OAuth integration. The manifest requires Node 22 or newer from a compatible host. Organization policy may restrict custom extensions. Manual bundle updates require installing the new version; no automatic directory updates are promised. GUI installation remains unverified separately from archive/protocol checks.

Manual config

Open Settings > Developer > Edit Config, or use your platform's config file:

{
  "mcpServers": {
    "beehiiv": {
      "command": "npx",
      "args": ["-y", "@thenavidm/beehiiv-mcp-cli@latest"],
      "env": {
        "BEEHIIV_API_KEY": "YOUR_API_KEY",
        "BEEHIIV_TOKENS_FILE": ""
      }
    }
  }
}

Replace the placeholders only in your private file. Merge the server entry into an existing mcpServers object instead of replacing other integrations. Fully quit and reopen Claude Desktop. Do not enable an extension and a manual entry with the same name; choose one route.

If a Windows launcher cannot execute npx directly, use "command": "cmd" with "args": ["/c", "npx", "-y", "@thenavidm/beehiiv-mcp-cli@latest"]. An absolute node executable and installed dist/index.js path also avoids launcher/PATH problems.

Cursor

Use private user settings at ~/.cursor/mcp.json, or Settings > Tools & MCP. Cursor documents environment interpolation and envFile support.

{
  "mcpServers": {
    "beehiiv": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/beehiiv-mcp-cli@latest"],
      "env": {
        "BEEHIIV_API_KEY": "${env:BEEHIIV_API_KEY}",
        "BEEHIIV_TOKENS_FILE": "${env:BEEHIIV_TOKENS_FILE}"
      }
    }
  }
}

The environment values must exist for the Cursor process. If you use envFile, keep that file private and outside version control. A project's .cursor/mcp.json must not contain actual credentials. Reconnect the server after saving.

VS Code and Copilot

Use MCP: Open User Configuration. VS Code uses servers and secure inputs, rather than a mcpServers root:

{
  "inputs": [
    {"type": "promptString", "id": "beehiiv-api-key", "description": "Beehiiv API key (leave empty for OAuth)", "password": true},
    {"type": "promptString", "id": "beehiiv-token-file", "description": "Optional private OAuth token-file path (leave empty for API key)"}
  ],
  "servers": {
    "beehiiv": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/beehiiv-mcp-cli@latest"],
      "env": {
        "BEEHIIV_API_KEY": "${input:beehiiv-api-key}",
        "BEEHIIV_TOKENS_FILE": "${input:beehiiv-token-file}"
      }
    }
  }
}

Start Beehiiv through the MCP controls, approve trust if prompted, and enter credentials in the private input prompts. Workspace .vscode/mcp.json may contain this placeholder-only structure, but never resolved secret values. Remote development runs the server in the selected remote environment, so local file paths refer to that environment.

Windsurf

Open Cascade's MCP settings or edit the private user file ~/.codeium/windsurf/mcp_config.json. Use the Claude Desktop manual mcpServers block above with your locally configured env values. See Windsurf's current MCP documentation. Restart or reconnect Beehiiv in Cascade; project files must not contain secrets.

Zed

Open Settings > AI > MCP Servers > Add Server > Add Local Server, or your user settings file. Zed uses context_servers:

{
  "context_servers": {
    "beehiiv": {
      "command": "npx",
      "args": ["-y", "@thenavidm/beehiiv-mcp-cli@latest"],
      "env": {
        "BEEHIIV_API_KEY": "YOUR_API_KEY",
        "BEEHIIV_TOKENS_FILE": ""
      }
    }
  }
}

Enter actual values only in private user settings. Check the active-server indicator before prompting. Do not wrap command and args inside a nested command object from older Zed examples.

Gemini CLI

Merge the Claude Desktop manual mcpServers block into your private ~/.gemini/settings.json. Configure the two env values locally, then restart Gemini CLI and inspect /mcp. See Gemini CLI's MCP configuration. Its project settings must not contain real credentials. You can instead use the CLI from an agent shell.

Other local stdio clients use the same command and arguments, adapted to their config format. A client that only accepts a remote MCP URL cannot connect directly: this package does not ship a public HTTP listener. ChatGPT's remote connector setup is not a substitute for local stdio installation.

Docker

Build locally from the reviewed source; no prebuilt registry image is claimed:

git clone https://github.com/thenavidm/beehiiv-mcp-cli.git
cd beehiiv-mcp-cli
docker build -t beehiiv-mcp-cli .
docker run --rm -i -e BEEHIIV_API_KEY beehiiv-mcp-cli

-e BEEHIIV_API_KEY forwards the shell's already configured private value. MCP needs -i and stdio. For OAuth, mount the private token file into the container with only the access needed for refresh, then set the in-container absolute BEEHIIV_TOKENS_FILE path. Host paths do not automatically exist inside a container. Restrict mounts and persist refreshed tokens if you need restart continuity.

Cline and other local MCP clients

Use the client's Add MCP server flow with command npx, arguments -y and @thenavidm/beehiiv-mcp-cli@latest, stdio transport, and private local BEEHIIV_API_KEY or BEEHIIV_TOKENS_FILE settings. UI names depend on the installed client. Reconnect and discover tools before an account call. Browser-only clients need a remote HTTPS connector; use Beehiiv's official server rather than this local stdio command.

Command inputs, JSON and output

Tool names become dashed commands: get_post becomes beehiiv-cli get-post. Both exact underscore tool names and dashed forms are accepted. Argument names have dashed aliases: post_id is --post-id. Use help and schema to discover each operation's current input.

beehiiv-cli tools
beehiiv-cli get-post --help
beehiiv-cli schema get-post
beehiiv-cli get-post --publication-id pub_00000000-0000-0000-0000-000000000000 --post-id post_00000000-0000-0000-0000-000000000000 --agent

Body flags and payload/payload_file are mutually exclusive. Path and query flags remain separate. Objects take JSON; array flags repeat once per array item. Do not pass an array to a flag that expects a single item:

beehiiv-cli list-subscriptions --publication-id pub_00000000-0000-0000-0000-000000000000 --limit 10 --agent
beehiiv-cli create-post --publication-id pub_00000000-0000-0000-0000-000000000000 --payload-file /absolute/private/path/newsletter.json --confirm --agent

Null and complete bodies

Use an actual JSON null in payload for nullable values. A shell --field null is a string. For example, a headers object can use null values to suppress inherited headers, per reviewed upstream prose. Discover the complete schema before editing nested fields.

Results go to stdout; errors are JSON on stderr. --select controls local result rendering, not the original API response. Arrays of objects use repeated JSON-item flags; payload/payload_file is easier for a complex post block tree.

Official MCP and community comparisons

COMPARISON.md records dated primary sources, API/MCP differences and pending evidence. No competitor token, latency or success-rate advantage is asserted.

Versions and migration

CHANGELOG.md records dated versions. Version 2 replaces the private MCP-only 1.0.0 source with current API coverage, a shared CLI and desktop packaging. Existing documented tool names remain where the current endpoints exist. Unsupported email-blast helpers are removed; use current post creation/update and the intended newsletter-list fields on eligible plans.

Use publication_id from list_publications, current prefixed resource IDs and native schemas. Review consent/reactivation/welcome-email fields, scheduling status and irreversible privacy operations. Private account instructions and old Git history remain private. Preserve the existing AGPL license.

Updates and removal

npm install -g @thenavidm/beehiiv-mcp-cli@latest
beehiiv-cli --version
claude mcp remove --scope user beehiiv
codex mcp remove beehiiv
npm uninstall -g @thenavidm/beehiiv-mcp-cli

Reinstall a newer desktop archive separately and restart affected clients. Remove manual client entries using its own settings. Uninstalling the package does not revoke Beehiiv credentials, remove private token/secret files or unschedule email. Revoke/delete keys or authorized apps in Beehiiv when appropriate. Inspect and remove private files yourself after preserving any private data you still need.

Pin a reviewed version instead of @latest if your automation requires reproducibility. Check CHANGELOG.md and GitHub Releases before a major update. Do not roll back by blindly publishing an older version over an existing npm version.

Validation and remaining evidence

Build, typecheck and 29 fixture/shared-CLI checks pass. Actual source and desktop discovery report 117 tools, with 70 in read-only mode. The production dependency audit has zero findings. Source and exact npm/desktop artifacts pass secret scans. Linux/Windows CI on Node 22 and 24 passed. Clean installation from public npm and discovery from the downloaded desktop release each verify 117 tools, or 70 in read-only mode. Both public artifacts pass secret scans.

Provider account writes, a desktop GUI installation and fresh model usage/task comparisons remain pending. No measured savings or broader coverage claim is invented. See SECURITY.md for the dev-only packaging advisory and RELEASE-CHECKLIST.md for the maintenance standard.