Skip to main content

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.2.1)​

ToolNeedsWhat it does
motorical_get_send_status—HTTP Send API health
motorical_mint_public_tokenak_live_…Mint Public Analytics bearer
motorical_list_motor_blocksbearer (auto)List motor blocks
motorical_send_emailmk_live_…POST /v1/send (default dryRun: true; optional fromName for display name)
motorical_get_messagebearer (auto)Message by UUID
motorical_get_message_eventsbearer (auto)Lifecycle events
motorical_sandbox_statusMOTORICAL_JWTDeveloper sandbox status
motorical_sandbox_allowlist_requestMOTORICAL_JWTEmail a 6-digit code to expand the sandbox allowlist (max 20 recipients) without converting
motorical_sandbox_allowlist_confirmMOTORICAL_JWTRedeem the allowlist-request code
motorical_sandbox_provisionMOTORICAL_JWTProvision *.sandbox.motorical.com + locked MB
motorical_sandbox_convertMOTORICAL_JWTPromote sandbox MB onto a verified domain
motorical_domain_addbearer (auto) or MOTORICAL_JWTAdd customer domain + DNS instructions — account-wide, no Motor Block needed
motorical_domain_listbearer (auto) or MOTORICAL_JWTList domains already on this account — self-diagnose a domain_add 409 conflict
motorical_domain_verifybearer (auto) or MOTORICAL_JWTVerify ownership + refresh DKIM/SPF/DMARC send-readiness; returns sendReady
motorical_domain_check_dnsbearer (auto) or MOTORICAL_JWTLive-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_handoffMOTORICAL_JWTMint CLI→browser one-time URL

The server registers 16 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 16.

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 and CLI --from-name.

CLI twin​

npm install -g https://docs.motorical.com/motorical-cli.tgz (Node 20+). The full path from nothing to a delivered message:

motorical signup you@example.com     # emails a 6-digit code
motorical verify 123456              # redeem it — this is what mints the JWT
motorical sandbox provision          # *.sandbox.motorical.com, outbound-locked
motorical send --to you@example.com --from hello@<handle>.sandbox.motorical.com --real

motorical verify is required — sandbox provision needs the JWT that it mints, so signup → sandbox provision cannot work on its own. And motorical send is a dry run unless you pass --real.

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).