sendpilot-actions

Secure local MCP server for SendPilot Lead Database searches and workspace read operations.

sendpilot-actions uses stdio and runs on your Mac. It keeps the SendPilot API key outside the repository and never writes it to Codex configuration or MCP output.

Scope

The server exposes exactly five tools:

Tool	Purpose
create_lead_database_search	Create a Lead Database search after explicit user confirmation and native macOS approval.
get_search_status	Read search status and progress.
get_search_results	Read paginated results for an existing search.
get_credits	Read the workspace credit balance.
list_campaigns	Read campaigns.

It does not send messages, send connection requests, create or modify campaigns, or add leads to campaigns.

Creating a search may consume credits. The tool requires confirmed: true and then presents a local macOS approval dialog with a bounded request summary and fingerprint. Declining or timing out prevents the API request.

Requirements

• Node.js 22 or newer
• macOS for the native approval dialog used by the create-search tool
• A SendPilot API key with access to the endpoints you intend to use

Install

git clone https://github.com/MarcoAIEH/sendpilot-actions.git
cd sendpilot-actions
npm ci
npm run build

Credentials

The default local credential file is ~/.config/sendpilot-actions/.env:

mkdir -p ~/.config/sendpilot-actions
chmod 700 ~/.config/sendpilot-actions
cp .env.example ~/.config/sendpilot-actions/.env
chmod 600 ~/.config/sendpilot-actions/.env

Set SENDPILOT_API_KEY in that file. Do not commit it. The loader rejects a non-private directory or file and rejects symlinks. A runtime SENDPILOT_API_KEY takes precedence, enabling a secret manager to inject the value without storing it in the repository.

Codex configuration

After building, register the stdio server without putting a secret in the configuration:

codex mcp remove sendpilot-actions
codex mcp add sendpilot-actions -- node "$(pwd)/dist/index.js"

Restart Codex or open a new task to load the tools.

Verification

npm test
npm run typecheck
npm run build
npm run smoke:readonly

smoke:readonly calls only GET /v1/credits and GET /v1/campaigns?status=all&page=1&limit=1. It does not create searches or modify any SendPilot resource.

Security notes

• API keys are read at runtime only; they are never logged or returned through MCP.
• Upstream error text is redacted before it reaches the MCP client.
• All input is validated and bounded before a local approval dialog can be shown.
• This repository is GitHub-only: private: true prevents accidental npm publication.

License

MIT