io.github.nirholas/hood-mcp

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.

Star History

Support the project

If robinhood-chain-mcp saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/robinhood-chain-mcp and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic
• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
• Questions or ideas: open an issue or start a discussion

Contributors