@runehand/mcp-server

MCP server that wraps the Runehand public API v1 as tools, so an MCP client (Claude Desktop, Claude Code, etc.) can operate Runehand bots directly: list bots and flows, read and reply to conversations, manage leads, and check analytics.

Setup

Generate an API key at https://app.runehand.co/settings/api-keys (requires a Pro or Enterprise plan, and the owner or admin role in the workspace). The plaintext key is shown once — copy it.
Add this to your MCP client's config (example: Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "runehand": {
      "command": "npx",
      "args": ["-y", "@runehand/mcp-server"],
      "env": { "RUNEHAND_API_KEY": "rh_live_..." }
    }
  }
}

Restart your MCP client. It should now list 9 Runehand tools.

Configuration

Env var	Required	Default	Purpose
`RUNEHAND_API_KEY`	Yes	—	Bearer token from `/settings/api-keys`.
`RUNEHAND_API_BASE_URL`	No	`https://app.runehand.co/api/v1`	Override for local/staging testing only.

Tools

Tool	Description
`list_bots`	List the bots that belong to the workspace that owns the API key.
`list_flows`	List the flows that belong to a bot, given the bot's UUID.
`get_flow`	Get a single flow, including its nodes in executable format.
`list_conversations`	List conversations, optionally filtered by `bot_id` and/or `status`.
`get_conversation`	Get a single conversation, including its messages.
`send_message`	Send a message as the agent in an existing conversation.
`list_leads`	List leads, optionally filtered by `bot_id` and/or `status`.
`create_lead`	Create a lead directly, without an associated conversation.
`get_analytics`	Get workspace KPIs and quick stats for a date range.

Errors from the Runehand API surface as tool errors in the form "{code}: {message}" (e.g. not_found: Not found.) — see the error codes table below.

Errors

All error responses from /api/v1/* use the same shape:

{
  "error": {
    "code": "plan_upgrade_required",
    "message": "Your current plan does not include API access.",
    "details": {
      "required_tiers": ["pro", "enterprise"]
    }
  }
}

details is null when not applicable.

Code	HTTP	When
`unauthenticated`	401	Missing header, invalid/revoked/expired token
`workspace_inactive`	403	Workspace is frozen or subscription lapsed
`plan_upgrade_required`	403	Workspace's plan doesn't include API access
`validation_failed`	422	Request data failed validation
`not_found`	404	Resource doesn't exist or doesn't belong to the key's workspace
`rate_limited`	429	Plan's requests-per-minute limit exceeded
`server_error`	500	Unhandled internal error

Development

npm install
npm run dev      # run directly with tsx, no build step
npm test         # vitest, mocks all HTTP via msw
npm run lint
npm run typecheck
npm run build     # compiles to dist/

License

MIT