Local MCP Server (npm package)

The full Motorical tool catalogue as a local stdio process — the standard shape for Cursor, Claude Desktop, and other MCP clients that launch a server as a subprocess rather than connecting to a remote URL.

Source: packages/motorical-mcp in motorical-smtp/motorical-packages (@motorical/mcp) — the public release mirror; day-to-day development happens in the private backend monorepo.

Install: npm install -g https://docs.motorical.com/motorical-mcp.tgz

Tools (v1.12.2)

Tool	Needs	What it does
motorical_get_send_status	—	HTTP Send API health
motorical_mint_public_token	ak_live_…	Mint Public Analytics bearer
motorical_list_motor_blocks	bearer (auto)	List motor blocks
motorical_send_email	mk_live_…	POST /v1/send (default dryRun: true; optional fromName for display name)
motorical_get_message	bearer (auto)	Message by UUID
motorical_get_message_events	bearer (auto)	Lifecycle events
motorical_wait_for_outcome	bearer (auto)	Poll a send until every recipient reaches a terminal outcome (delivered/bounced/failed) — the only place a multi-recipient send's per-recipient results are visible
motorical_get_message_by_smtp_id	bearer (auto)	Look up one message by exact SMTP Message-ID — a lookup, not a listing
motorical_get_overview	bearer (auto)	Motor Block overview — volume + health snapshot, from/to
motorical_get_daily_summary	bearer (auto)	Daily send summary, days window
motorical_get_metrics	bearer (auto)	Time-series metrics, from/to/interval (hour|day)
motorical_get_deliverability	bearer (auto)	Deliverability breakdown
motorical_get_reputation	bearer (auto)	Sending reputation snapshot
motorical_get_anomalies	bearer (auto)	Detected sending anomalies
motorical_get_providers	bearer (auto)	Delivery breakdown by receiving provider
motorical_get_error_codes	bearer (auto)	Bounce/error code breakdown
motorical_get_config	bearer (auto)	Motor Block configuration
motorical_get_domain_health	bearer (auto)	DKIM/SPF/DMARC health for the Motor Block's domain, optional refresh
motorical_get_rate_limits	bearer (auto)	Per-Motor-Block rate limit status
motorical_get_account_rate_limits	bearer (auto)	Account-wide rate limit ceiling — account-wide, no Motor Block needed
motorical_get_onboarding_state	bearer (auto)	Composed account state — domain verification, DNS readiness, Motor Block existence, sandbox status in one call — account-wide, no Motor Block needed
motorical_get_logs	bearer (auto)	Send/event log search — recipients masked unless the logs.pii scope is granted
motorical_sandbox_status	MOTORICAL_JWT	Developer sandbox status
motorical_sandbox_allowlist_request	MOTORICAL_JWT	Email a 6-digit code to expand the sandbox allowlist without converting (the response says when the allowlist is full)
motorical_sandbox_allowlist_confirm	MOTORICAL_JWT	Redeem the allowlist-request code
motorical_sandbox_provision	MOTORICAL_JWT	Provision the sandbox on a Motorical-owned .sandbox domain (instant, no DNS) + locked MB. A Free account that adds and fully verifies its own domain gets a sandbox MB on it automatically when automatic provisioning is enabled (otherwise call this tool); see Two ways to start
motorical_sandbox_convert	MOTORICAL_JWT	Promote sandbox MB onto a verified domain; optional production name/type; replaces the SMTP username (password, API keys and auth method unchanged)
motorical_free_recipient_add	MOTORICAL_JWT	Email a person a confirmation link so a Free account may send test email to them; they must click it, the tool never confirms
motorical_free_recipient_list	MOTORICAL_JWT	List the addresses asked, with status, limit and usage
motorical_free_recipient_remove	MOTORICAL_JWT	Remove an address by id (asks for confirmation)
motorical_domain_add	bearer (auto) or MOTORICAL_JWT	Add customer domain + DNS instructions — account-wide, no Motor Block needed
motorical_domain_list	bearer (auto) or MOTORICAL_JWT	List domains already on this account — self-diagnose a domain_add 409 conflict
motorical_domain_verify	bearer (auto) or MOTORICAL_JWT	Verify ownership + refresh DKIM/SPF/DMARC send-readiness; returns sendReady
motorical_domain_check_dns	bearer (auto) or MOTORICAL_JWT	Live-check DKIM/SPF/DMARC and persist dkim_configured/spf_configured. Required before /v1/send when ownership is verified but send returns DOMAIN_DNS_INCOMPLETE
motorical_web_handoff	MOTORICAL_JWT	Mint a one-time browser handoff URL
motorical_motor_block_list	MOTORICAL_JWT	List your production Motor Blocks (inactive included) — account-wide
motorical_motor_block_create	MOTORICAL_JWT	Create a production Motor Block on a verified domain; needs a UUID v4 idempotencyKey. Runs under your dashboard session, so — like the dashboard — it can return credentials once at creation (the hosted server never does)
motorical_motor_block_rename	MOTORICAL_JWT	Display name only; never changes the SMTP username
motorical_motor_block_change_type	MOTORICAL_JWT	Switch transactional ⇄ general_purpose (asks for confirmation)
motorical_motor_block_assign_domain	MOTORICAL_JWT	Move a block onto another verified domain (asks for confirmation)
motorical_motor_block_deactivate	MOTORICAL_JWT	Reversible pause (asks for confirmation)
motorical_motor_block_reactivate	MOTORICAL_JWT	Resume a paused block
motorical_motor_block_delete	MOTORICAL_JWT	Permanent, asynchronous, irrecoverable delete; block must be deactivated first; deleteHistory is explicit (asks for confirmation)
motorical_motor_block_delete_status	MOTORICAL_JWT	Poll a deletion by jobId
motorical_webhook_list	bearer (auto)	List webhook endpoints on a Motor Block
motorical_webhook_create	bearer (auto)	Register a webhook endpoint — returns the signing secret once
motorical_webhook_update	bearer (auto)	Update a webhook's url/events/enabled state
motorical_webhook_delete	bearer (auto)	Delete a webhook endpoint
motorical_webhook_test	bearer (auto)	Send a synthetic test delivery
motorical_webhook_get_deliveries	bearer (auto)	Recent delivery attempts for a webhook
motorical_webhook_get_stats	bearer (auto)	Delivery success/failure counts and latency

The server registers 51 tools, 1 prompt, and 2 resources:

Resources: motorical://docs/llms.txt, motorical://docs/openapi.json — the live OpenAPI document is exposed as a resource, so an agent works from the current contract instead of guessing at it. Prompt: motorical_integrate_send — guidance for integrating transactional email safely; takes an optional language argument (node, python, curl). It is a prompt, not a tool, and is not counted among the 51.

Recipient addresses in motorical_get_logs and motorical_get_message_by_smtp_id results are masked, same as on the hosted OAuth server: both mint a bearer token with a fixed default scope list (logs.read, analytics.read, webhooks.manage, config.read) that never includes logs.pii, so includePII: true gets the backend's 403 regardless of whether the underlying credential is an ak_live_ key or MOTORICAL_JWT.

Real sends require dryRun: false and confirmRealSend: true. Sandbox outbound is allowlist-locked until convert. Pass optional fromName (not a From header) for the inbox display name — same field as HTTP /v1/send.

Getting a dashboard login token (MOTORICAL_JWT)

The sandbox allowlist and handoff tools on this server use a dashboard session token. Get one over REST; nothing needs installing. Base URL https://api.motorical.com/api/auth.

curl -X POST https://api.motorical.com/api/auth/register -H 'Content-Type: application/json' -d '{"email":"you@example.com"}'    # emails a 6-digit code
curl -X POST https://api.motorical.com/api/auth/verify-code -H 'Content-Type: application/json' -d '{"email":"you@example.com","code":"123456"}'    # returns a single-use setupToken (valid 30 minutes)
curl -X POST https://api.motorical.com/api/auth/set-password -H 'Content-Type: application/json' -d '{"email":"you@example.com","password":"<choose one>","setupToken":"<from verify-code>","channel":"agent"}'    # returns token + refreshToken

set-password is what returns the JWT and refresh token. Refresh with POST /api/auth/refresh and { "refreshToken": "…" }. With a person present and an OAuth-capable client, the hosted server needs none of this.

Journey: onboarding-sandbox-journey.json.

Dashboard JWT APIs: GET /api/developer/sandbox, POST /api/developer/sandbox/provision, PATCH /api/developer/sandbox/outbound, POST /api/developer/sandbox/convert.

Cursor configuration

{
  "mcpServers": {
    "motorical": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/motorical-mcp/src/index.js"],
      "env": {
        "MOTORICAL_MK_API_KEY": "mk_live_…",
        "MOTORICAL_AK_API_KEY": "ak_live_…",
        "MOTORICAL_JWT": "dashboard-jwt-from-login",
        "MOTORICAL_MOTOR_BLOCK_ID": "your-motor-block-uuid",
        "MOTORICAL_DEFAULT_FROM": "noreply@yourdomain.com"
      }
    }
  }
}

Downloadable template: motorical-mcp.cursor.json

Environment variables

See the package README. Keys are created in the Motorical dashboard (Motor Block API keys + Account API keys).

Related

• Motorical MCP overview — which server to use
• Hosted MCP Resource Server (OAuth) — no install, if your client supports it
• AI Agent Quickstart
• SMTP Authentication Methods