Flodesk MCP Server & CLI

What is the Flodesk MCP server & CLI?

The Flodesk MCP server & CLI is a free, open source program that lets AI agents read and change requested Flodesk account data with explicit approval 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 to the fixed Flodesk API origin using the selected private API key or externally minted OAuth token.

The CLI is the same program as commands. flodesk-cli list-subscribers runs the same code your AI runs when you deliberately read one intended subscriber page, 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
Read these subscribers and their exact native statuses.
Upsert only the subscriber records and opt-in data I approve.
Inspect these workflows and enroll only the requested subscriber.
Review these ordered native requests and show the exact hash.
Apply only that matching batch and keep partial receipts.
Publish the approved Canva or Studio export as a draft.

Flodesk already offers an official MCP with analytics, cohort filtering, CSV export and robust bulk confirmation tokens. This companion adds verified local CLI/stdio workflows for the current native public API, including drafts, custom fields, webhooks, explicit workflow enrollment and 50-subscriber upserts.

How to install the Flodesk MCP server

Choose the shared CLI, local stdio MCP or versioned desktop bundle. Codex comes first, followed by every declared client and operating system.

Set up Flodesk access

Private integration API key

1. Sign into the intended Flodesk account. Open Account → Integrations → API, or the API key settings. Check which account owns the audience before creating/copying a key.
2. Use a private integration API key for your own account. The native docs describe full API access; this package does not invent per-operation key scopes or guarantee provider read-only keys. Local read-only policy is a separate control.
3. Save FLODESK_API_KEY only in private user/client environment settings, or use FLODESK_TOKEN_FILE as an absolute token-only file outside repositories. On macOS/Linux use a private 0700 directory and owner-private 0600 regular non-symlink file, at most 64 KiB. On Windows restrict file/parent ACLs to yourself; POSIX mode checks do not establish Windows ACLs.
4. Run flodesk-cli doctor for local settings. Deliberately run doctor --network to read one subscriber page with per_page=1; output reports only count, not the subscriber record. That verifies one read, not account-owner identity, campaign/webhook access or all native permissions.
5. Inspect exact native fields and IDs, then approve only requested work. Double opt-in, segment additions and workflow enrollment can trigger actual messages. Do not create subscribers, opt-ins, workflow entries, drafts or webhooks merely to test installation.

The API key is an HTTP Basic username, with an empty password. The client constructs Authorization: Basic base64(key:), sends a descriptive User-Agent and uses only the allowlisted https://api.flodesk.com origin. No API key goes into a URL, prompt, Git file or log. It refuses redirects and unknown routes.

Externally minted partner OAuth

Native partner OAuth requires a provider-approved integration with its own client ID/secret and redirect flow. This package accepts an externally minted FLODESK_ACCESS_TOKEN or named access_token profile as Authorization: Bearer. It does not register an app, start login, exchange authorization codes, refresh tokens or import official connector sessions.

Access tokens are documented as 24 hours; refresh tokens are single-use and rotate. Refreshing belongs to your approved private integration and must store its newly issued refresh token securely. This runtime never holds that client secret/refresh token. Restart after replacing its access token. get_oauth_userinfo makes only the fixed /oauth2/userinfo GET and refuses API-key profiles before any request.

For a token file containing an OAuth access token, set FLODESK_AUTH_TYPE=oauth for a direct profile, or auth_type:"oauth" in that named profile. File credentials otherwise default to API key. Never configure api_key and access_token together. A selected file overrides only its own profile's inline credential; profiles never inherit a global key/token or another account.

Several private accounts

FLODESK_ACCOUNTS is a private JSON array of unique {name,api_key,access_token,token_file,auth_type} entries. Choose exactly one credential type in each. FLODESK_DEFAULT_ACCOUNT and --account select exact labels. Labels and review hashes are not verified provider ownership. Token files cache until process restart. list_accounts returns only labels/default/auth type/credential source, without token paths or provider reads.

Official MCP connection

Flodesk already supplies its official MCP and setup help. Its production field reference currently lists 35 tools, including email/form/checkout/workflow analytics, cohort filters, subscriber actions, CSV export and bulk archive/unarchive/segment changes. Its previews issue single-use confirmation tokens expiring after 120 seconds. Those capabilities and safeguards already exist.

The September 11 help article describes an earlier 24-tool/individual-action phase and says bulk work is upcoming; the current production catalog describes 35 tools and bulk workflows. Treat that as documented source drift. Marketing's broad future-control examples do not establish current send/schedule support. This local public-REST package does not call private MCP-only analytics/cohort routes or accept the hosted connector's confirmation tokens.

Quotas and effects

The AGPL wrapper is free; Flodesk subscription/API eligibility and account policies remain separate. Native REST limits are 100 requests/minute normally and 20/minute for POST /subscribers/batch, up to 50 subscribers per request. X-Fd-RateLimit headers report remaining capacity. Our process spacing defaults 650 ms, plus a separate 3100 ms batch window. Other processes/apps share account quota; local pacing is not provider enforcement or a guaranteed distributed limiter.

No automatic retries, including reads, 429, 5xx, redirects or timeouts. A failed write can leave an unknown result, duplicate webhook/segment or triggered message. Inspect provider state before deliberately repeating. JSON requests cap 1 MiB and responses 5 MiB. Each native list returns one page with its own meta/page semantics, not an all-pages backup. Workflow statuses use native CSV and perPage; campaign query names retain native capitalization.

Canva and Studio publish draft campaign exports, not send/schedule emails. Subscriber upsert can create or update by id/email; up to 50 segment IDs are supported. double_optin applies only to newly created subscribers and can send a confirmation message. Workflow re-entry needs prior completion and Allow repeat subscribers; abandoned-cart workflows cannot be enrolled through this route. Unsubscribe changes subscription state without pretending to delete the record. Removing segment membership is distinct and sends the required native DELETE JSON body.

Revocation and retained data

Revoke the intended key at Flodesk, replace private settings/files and restart. Revoke partner OAuth/official connector authorization separately. Package/client removal does not undo audience changes, sent opt-ins/workflow effects, drafts, webhooks or private audience-page files. Retain receipts and investigate unknown outcomes before explicitly requested cleanup.

Check that it works

Begin with local discovery and settings, then deliberately opt into one subscriber read.

flodesk-cli --version
flodesk-cli doctor
flodesk-cli list-accounts --agent
flodesk-cli doctor --network

flodesk-cli --version
flodesk-cli tools
flodesk-cli list-accounts --agent
flodesk-cli doctor
flodesk-cli doctor --network
flodesk-cli list-subscribers --per-page 1 --agent --select meta,data.id

The release validates shared full/read-only discovery and native request fixtures. Actual authenticated provider reads/writes, desktop GUI installation and matched successful Codex task/token measurements require their own evidence. doctor without --network checks local configuration only. One successful subscriber read does not prove ownership or every permission; never trigger opt-ins/workflows to test installation.

Use the Flodesk CLI

The CLI is the same 32 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_subscribers runs as flodesk-cli list-subscribers.

flodesk-cli tools
flodesk-cli list-subscribers --help
flodesk-cli schema batch-create-or-update-subscribers
flodesk-cli list-subscribers --per-page 5 --account work --agent
flodesk-cli get-subscriber --id-or-email YOUR_SUBSCRIBER_ID --account work --agent

The bare flodesk-cli lists every command, and flodesk-cli <command> --help shows what a command takes. All 16 mutations/private-file operations require --confirm. --agent/--yes never approve work. Repeat --tasks once per JSON object; complete native bodies may use an absolute private payload_file.

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 tools. Codex can connect to the local MCP server or run the CLI directly. Neither requires Claude Code.

MCP provides structured tool discovery; the CLI supports scripts, compact JSON, field selection and command/schema discovery. Official hosted MCP connection and local CLI authentication have different setup requirements.

Codex-specific token measurements are pending. Record the actual client/model versions, discovery configuration, input/output usage, caching, latency and equivalent successful outcomes. Standing definitions and full task cost are separate measurements; CLI commands, selected help, results and reasoning still consume tokens.

No efficiency percentage or Claude-derived figure is presented as a Codex result. Other-client benchmarks can be added separately.

Subscriber, draft and workflow examples

Start with one intended account and exact IDs. Read current subscriber status/membership, segment colors and available workflow IDs before approving changes. Do not infer consent or enroll all matching rows from a display name. Native upsert accepts id or email; optional optin_ip/optin_timestamp preserve supplied provenance rather than inventing it. Its status filter now includes unconfirmed, cleaned and archived.

Use native batch upsert for 1–50 explicit subscribers. It is distinct from the official MCP's dynamic-cohort archive/export actions. Inspect every successes/failures item and repeat only an explicitly reviewed correction after resolving unknown outcomes.

Segment removal changes membership and retains the subscriber record; unsubscribe changes subscription state. Workflow addition can trigger real automation messages and is refused until confirmed. Provider re-entry/completion/abandoned-cart restrictions still apply; the wrapper does not circumvent them.

Create a webhook only for the explicitly chosen HTTPS receiver and requested native events. No receiver is called by this local client. Event delivery is provider behavior after configuration; a creation response is not a receiver/test-delivery success. Native public REST does not expose a signing-key creation/rotation endpoint, and none is invented.

Publish reviewed native HTML via publish_studio_email, or an approved exported bundle_url via publish_canva_email. These create/update draft campaigns; sending/scheduling remains outside this API. The old blanket statement that no campaign creation exists is corrected. Never treat a returned draft URL as a sent campaign receipt.

flodesk-cli get-subscriber --id-or-email YOUR_SUBSCRIBER_ID --account work --agent
flodesk-cli list-workflows --agent
flodesk-cli get-operation-schema --operation publish_studio_email --agent
flodesk-cli create-or-update-subscriber --help
flodesk-cli save-subscriber-page --per-page 1 --output-file /absolute/private/page-001.json --account work --confirm --agent

Exact ordered batch review and pagination

preview_subscriber_batch is fully local: validate 1–20 ordered subscriber/segment/workflow/custom-field tasks against current packaged schemas and native semantics. It loads no key/file and makes no provider read. SHA-256 binds ordered exact requests/tasks, selected profile label/auth type and snapshot. It is not a real-cohort preview, final recipient count, cryptographic approval, current provider-state lock or verified account ownership. A changed key can keep the same label.

submit_subscriber_batch requires explicit confirmation and the matching hash. Every task is validated before the first request. Native batch-upsert tasks may each affect 50 subscribers:20 tasks is not a 20-recipient budget. Stop on first failure, partial native HTTP 200 result or incomplete native receipt, returning knownResults/failedIndex/unattemptedIndices without automatic retry, replay, rollback or implicit continuation. Earlier subscriber/workflow effects can persist.

Official preview_bulk_change and preview_segment_count already count real filtered audiences, issue single-use 120-second tokens and validate cohort growth. Our exact local ordered REST review has a different purpose and cannot replace those safeguards. Hosted tokens are not accepted here.

Native lists return one meta page. Carry the actual route's page/per_page or workflow page/perPage with unchanged filters/account. list_all_custom_fields is a named native all-fields route, not a generic automatic all-pages loop. Local perPage cap 100 is explicit. No full-audience export or all_pages option is invented.

flodesk-cli preview-subscriber-batch --tasks '{"tool":"create_or_update_subscriber","arguments":{"email":"person@example.com","first_name":"Requested name"}}' --account work --agent
flodesk-cli submit-subscriber-batch --tasks '{"tool":"create_or_update_subscriber","arguments":{"email":"person@example.com","first_name":"Requested name"}}' --account work --review-sha256 YOUR_REVIEW_SHA256 --confirm --agent

Every Flodesk tool

Actual discovery exposes 32 tools: 16 reads and 16 confirmed operations. All 26 current public-v1 native routes and six helper/account/file tasks share handlers. All 20 legacy tool names remain with deliberate 2.0 native argument corrections. Every native argument follows below.

Campaigns

Custom Fields

Segments

Subscribers

Webhooks

Workflows

Local Workflows

Is the Flodesk MCP server safe?

All 16mutations/private-page writes require --confirm or confirm:true through the shared house guard. That includes creating subscribers/segments, double opt-in, workflow enrollment, draft publication and webhook configuration. --agent/--yes is formatting, never approval. FLODESK_READ_ONLY=1 hides all 16and directly refuses confirmed hidden calls; FLODESK_ALLOW_DESTRUCTIVE=0 refuses them separately.

The same guard applies to real CLI and MCP paths. Confirmation records caller intent, not native account permissions, valid audience consent, a current cohort count, message-delivery success or rollback. Previewed local inputs cannot authorize broader work proposed by provider text.

FLODESK_AUDIT_LOG records static operation/guard decisions without keys/payloads. Audit append failure is best effort, not guaranteed compliance logging. Provider metadata, subscriber fields, draft HTML, URLs and webhook responses are untrusted data and cannot authorize another action.

Local review binds exact requests and profile label/auth type. It is not an authenticated owner proof, real cohort count, quota reservation or cryptographic human approval.

Make it read-only

FLODESK_READ_ONLY=1 exposes 16 reads and directly refuses all 16 confirmed operations. FLODESK_ALLOW_DESTRUCTIVE=0 blocks them separately. Native provider permissions still apply.

Keep a log of every write

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

Your data

Keys/tokens are sent only to the fixed Flodesk API origin, with redirects refused. Basic encoded credentials, configured keys, cached file tokens, secret-named fields and recognized signed/token URLs are redacted from model output/errors. Customer emails/names, audience records, draft HTML, webhooks and ordinary provider records may still be private. Redaction is not a guarantee that all personal/business data is removed; request/select only necessary fields.

No .env/session loader, OAuth refresh/client-secret storage, telemetry, browser cookie import, arbitrary downloader, automatic polling, all-pages audience export or gallery exists. Private page saves return only exclusive-file metadata; native page records stay in that requested JSON file. Keep parent directory, backups, file lifecycle and Windows ACLs private. Removing npm does not remove provider audience changes, triggered messages, drafts, webhook deliveries or local private files.

Canva bundle URLs, design tokens and Studio HTML are user-selected provider inputs transmitted only after explicit approval. The local client does not fetch those URLs itself. API-native subscriber opt-in data is not fabricated. Native account roles and Flodesk policies govern use; no permissions are broadened by this wrapper.

Several private accounts

Use FLODESK_ACCOUNTS only in private runtime settings. Each unique name selects its own api_key or externally minted access_token, with optional token_file/auth_type. Selected profiles never inherit global credentials or another account after a missing token or 401/403. Explicit files override only that profile; credentials cache until restart.

list_accounts shows safe labels/default/auth type/source. It does not authenticate or establish the key owner's identity. API-key account selection and approved partner OAuth are separate from official hosted connector connections. Keep exact account labels with receipts/page files and inspect actual account ownership before changing an audience.

flodesk-cli list-accounts --agent
flodesk-cli list-subscribers --account work --per-page 1 --agent

Flodesk MCP server settings

Keep keys, tokens, files and profile JSON outside repositories. GUI and remote runtimes have separate settings and filesystems. No automatic .env, OAuth refresh or hosted-session import occurs.

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.

Every tool argument and native input

list_campaigns

List campaigns.

Kind: Read. Native account permissions and local semantics still apply.

publish_canva_email

Publish a Canva email design as a draft campaign.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.payload

get_canva_design_state

Get the latest Canva design state for auto-selecting campaigns.

Kind: Read. Native account permissions and local semantics still apply.

publish_studio_email

Publish a Studio email export as a draft campaign.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.payload

list_custom_fields

List all custom fields (pagination).

Kind: Read. Native account permissions and local semantics still apply.

create_custom_field

Create a custom field.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.payload

list_all_custom_fields

List all custom fields.

Kind: Read. Native account permissions and local semantics still apply.

list_segments

List all segments.

Kind: Read. Native account permissions and local semantics still apply.

create_segment

Create a segment.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.payload

list_segment_colors

List all segment colors.

Kind: Read. Native account permissions and local semantics still apply.

get_segment

Retrieve a segment.

Kind: Read. Native account permissions and local semantics still apply.

list_subscribers

List all subscribers.

Kind: Read. Native account permissions and local semantics still apply.

create_or_update_subscriber

Create or update a subscriber.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.custom_fields

input.custom_fields.{key}

Native JSON value; inspect the full schema for validation.

input.segment_ids

input.segment_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

input.payload.custom_fields

input.payload.custom_fields.{key}

Native JSON value; inspect the full schema for validation.

input.payload.segment_ids

input.payload.segment_ids[]

Native JSON value; inspect the full schema for validation.

batch_create_or_update_subscribers

Create or update up to 50 subscribers in a single request.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.subscribers

input.subscribers[]

input.subscribers[].custom_fields

input.subscribers[].custom_fields.{key}

Native JSON value; inspect the full schema for validation.

input.subscribers[].segment_ids

input.subscribers[].segment_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

input.payload.subscribers

input.payload.subscribers[]

input.payload.subscribers[].custom_fields

input.payload.subscribers[].custom_fields.{key}

Native JSON value; inspect the full schema for validation.

input.payload.subscribers[].segment_ids

input.payload.subscribers[].segment_ids[]

Native JSON value; inspect the full schema for validation.

get_subscriber

Retrieve a subscriber.

Kind: Read. Native account permissions and local semantics still apply.

remove_subscriber_from_segments

Remove the subscriber from segments.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.segment_ids

input.segment_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

input.payload.segment_ids

input.payload.segment_ids[]

Native JSON value; inspect the full schema for validation.

add_subscriber_to_segments

Add the subscriber to segments.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.segment_ids

input.segment_ids[]

Native JSON value; inspect the full schema for validation.

input.payload

input.payload.segment_ids

input.payload.segment_ids[]

Native JSON value; inspect the full schema for validation.

unsubscribe

Unsubscribe from all lists.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

list_webhooks

List all webhooks.

Kind: Read. Native account permissions and local semantics still apply.

create_webhook

Create a webhook.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.events

input.events[]

Native JSON value; inspect the full schema for validation.

input.payload

input.payload.events

input.payload.events[]

Native JSON value; inspect the full schema for validation.

delete_webhook

Delete a webhook.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

get_webhook

Retrieve a webhook.

Kind: Read. Native account permissions and local semantics still apply.

update_webhook

Update a webhook.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.events

input.events[]

Native JSON value; inspect the full schema for validation.

input.payload

input.payload.events

input.payload.events[]

Native JSON value; inspect the full schema for validation.

list_workflows

List workflows.

Kind: Read. Native account permissions and local semantics still apply.

input.statuses

input.statuses[]

Native JSON value; inspect the full schema for validation.

add_subscriber_to_workflow

<br><b>Notes:</b> <ul> <li>In order for a subscriber to be added to a workflow subsequent times, (1) the subscriber has to have already completed the workflow, i.e. they cannot currently be active in the workflow, and (2) the "Allow repeat subscribers" setting for the workflow must be toggled on.</li> <li>Subscribers cannot be added to abandoned cart workflows using this endpoint.</li> </ul>

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.payload

remove_subscriber_from_workflow

Remove a subscriber from workflow.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

list_accounts

Local profile labels/default/auth method only. No keys, token paths, provider identity or network request.

Kind: Read. Native account permissions and local semantics still apply.

Native JSON value; inspect the full schema for validation.

get_operation_schema

Local reviewed method/path/query/body schema and provenance for one native tool. No credentials or provider request.

Kind: Read. Native account permissions and local semantics still apply.

get_oauth_userinfo

One fixed UserInfo GET for an explicitly selected externally minted OAuth access token. API keys refuse; no refresh, OAuth login or fallback.

Kind: Read. Native account permissions and local semantics still apply.

preview_subscriber_batch

Local validation and SHA-256 of exact ordered subscriber/segment/workflow/custom-field work, selected profile label and reviewed schema. No provider reads, key load, identity check, price or rollback guarantee.

Kind: Read. Native account permissions and local semantics still apply.

input.tasks

input.tasks[]

submit_subscriber_batch

Confirmed one-to-twenty ordered subscriber/segment/workflow/custom-field tasks. Prevalidate all and verify exact hash before first request. Stop on first failure with known results/failed index/unattempted indices; no retries, rollback or implicit continuation.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

input.tasks

input.tasks[]

save_subscriber_page

Confirmed one-page GET saved only to an exclusive new0600 JSON file. No CSV/cohort export, all-pages loop, overwrite, automatic upload or browser preview.

Kind: Confirmed operation. Native account permissions and local semantics still apply.

##### Native list_campaigns: GET /campaigns

List campaigns.