@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

1. 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.
2. 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_..." }
    }
  }
}

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