hood-mcp

Model Context Protocol servers for Robinhood Chain (chain ID 4663).

Two servers, one package: a zero-config data server any MCP client can add in one line, and an explicitly opt-in trading server for wallets that want to act. Built on hoodchain, the TypeScript SDK for the chain.

Docs: https://nirholas.github.io/robinhood-chain-mcp/

Why

Robinhood Chain has two other MCP servers today, both zero-star, days-old, read-only hobby projects. This is the productized one: a full data surface (Stock Tokens, memecoins, launches, chain stats) plus a guarded trading surface with hard spend caps and a confirm gate — built to the standard three.ws holds its agent tooling to.

60-second install

Claude Code

claude mcp add hood-mcp -- npx -y hood-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hood-mcp": {
      "command": "npx",
      "args": ["-y", "hood-mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "hood-mcp": {
      "command": "npx",
      "args": ["-y", "hood-mcp"]
    }
  }
}

Any stdio MCP client

npx -y hood-mcp

No API key, no wallet, no config. It talks to the public Robinhood Chain RPC and starts answering tool calls immediately.

Two servers

1. hood-mcp — data server (zero-config, read-only)

stdio by default; pass --http (or HOOD_MCP_TRANSPORT=http) for Streamable HTTP on HOOD_MCP_PORT (default 8730), serving POST /mcp and GET /health.

HOOD_MCP_NETWORK=mainnet   # or testnet — default mainnet
ALCHEMY_KEY=                # optional: private RPC instead of public

2. hood-mcp-trading — wallet server (explicitly opt-in)

Separate binary, stdio only, refuses to start unless both are set:

HOOD_MCP_ENABLE_TRADING=1
ROBINHOOD_CHAIN_PRIVATE_KEY=0x...

{
  "mcpServers": {
    "hood-mcp-trading": {
      "command": "npx",
      "args": ["-y", "hood-mcp-trading"],
      "env": {
        "HOOD_MCP_ENABLE_TRADING": "1",
        "ROBINHOOD_CHAIN_PRIVATE_KEY": "0xYOUR_KEY"
      }
    }
  }
}

See Safety model for the full guard design. Summary:

1. Kill switch — the server process itself refuses to start without HOOD_MCP_ENABLE_TRADING=1.
2. Eligibility gate — buying a tokenized Stock Token requires HOOD_MCP_ACKNOWLEDGE_ELIGIBILITY=1 (Stock Tokens are barred to US/Canada/UK/Switzerland persons — see below).
3. Spend caps — every mutating call is valued in USD and checked against HOOD_MCP_MAX_SPEND_USDG (per-call) and HOOD_MCP_MAX_SESSION_USDG (per-session, in-memory, resets on restart) before anything is signed.
4. Confirm gate — the first call to execute_swap / transfer_usdg always returns a simulation (recipient, amount, token, min-received) and signs nothing. Only a second call with confirm: true and identical arguments broadcasts.

HOOD_MCP_MAX_SPEND_USDG=25        # default 25 — per single call
HOOD_MCP_MAX_SESSION_USDG=100     # default 100 — cumulative for the process lifetime
HOOD_MCP_ACKNOWLEDGE_ELIGIBILITY=0  # set to 1 ONLY if eligible to hold Stock Tokens

Stock Tokens are tokenized debt securities (issuer: Robinhood Assets (Jersey) Ltd) and may not be offered, sold, or delivered to US persons (additional limits: Canada, UK, Switzerland). The restriction is legal/front-end enforced, not contract-level — execute_swap throws unless the operator has explicitly acknowledged eligibility. Memecoins are unrestricted.

Environment reference

See .env.example for the full annotated list. Nothing is required for the data server; the trading server requires the two kill-switch variables above.

x402 monetization (seam, not active)

The HTTP transport has a documented seam (src/x402-seam.ts) to paywall future metered tools (deep history, firehose) via the sibling hood402 USDG-on-Robinhood-Chain x402 rail once it exists. Every tool this package ships today stays free regardless.

Development

npm install
npm run build        # tsup → dist/
npm run dev:data      # tsx src/data-server.ts (stdio)
npm run dev:trading   # tsx src/trading-server.ts (stdio, needs env)
npm test              # hermetic: schema + guard tests (real network reads, no wallet funds)
npm run test:live      # live: every data tool against real mainnet 4663 data
npm run test:swap       # live, gated: a REAL testnet swap through execute_swap (needs a
                        # faucet-funded ROBINHOOD_CHAIN_PRIVATE_KEY — see the test file)

Depends on hoodchain from npm; for local development against an unpublished SDK checkout: npm i ../robinhood-chain-sdk.

Registry submissions (owner action)

Metadata is prepared, not submitted — publishing to a registry is a one-way, attributed action the owner should take:

• modelcontextprotocol registry — server.json in this repo validates against the official schema. Submit with the mcp-publisher CLI once hood-mcp is live on npm.
• Smithery — their current flow publishes a running server URL or an .mcpb bundle (smithery mcp publish <url> -n <org/server>), not a static config file. Deploy the HTTP transport (hood-mcp --http) somewhere public, then run smithery mcp publish https://your-deployment/mcp -n nirholas/hood-mcp.

License

All rights reserved. See LICENSE.