Meta Agent Tools
PT

Back to the catalog

io.github.nirholas/hood-mcp

Robinhood Chain data + guarded trading for AI agents: Stock Token quotes, portfolios, launches

Open source Open in the app JSON README (API)

About

Robinhood Chain data + guarded trading for AI agents: Stock Token quotes, portfolios, launches

Details

Kind
MCP servers
Topic
Finance & crypto
Publisher
nirholas
Origin
official
Category
ferramentas
Transport
local
Version
0.1.1
Stars
4
Forks
1
Last push
2026-08-17T02:55:30Z
Repository state
ativo
Language
TypeScript
License
NOASSERTION
Added
2026-08-29 04:00:54
Updated
2026-08-29 04:00:54
Origin id
io.github.nirholas/hood-mcp

README

# hood-mcp

**Model Context Protocol servers for [Robinhood Chain](https://docs.robinhood.com/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`](https://nirholas.github.io/robinhood-chain-sdk/), 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

```bash
claude mcp add hood-mcp -- npx -y hood-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

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

### Cursor

Add to `.cursor/mcp.json`:

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

### Any stdio MCP client

```bash
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`.

| Tool | What it does |
|---|---|
| `get_chain_stats` | Latest block, gas price, TVL, network totals. |
| `list_stock_tokens` | The 95-token Stock Token registry (ticker, name, contract, feed). |
| `get_stock_quote` | Chainlink price + Uniswap DEX price + premium/discount + share price for a ticker. |
| `get_portfolio` | Multiplier-correct Stock Token portfolio + USDG balance for any address. |
| `get_coin` | Price/volume/liquidity/holders for any token by address (memecoin or Stock Token). |
| `list_trending_coins` | The chain's trending pools right now. |
| `get_recent_launches` | Recent NOXA + The Odyssey launches, scanned from on-chain logs. |
| `watch_launches` | Watch live for new launches for up to 120s. |
| `search_token` | Find a token by ticker, name, or address. |

```bash
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:

```bash
HOOD_MCP_ENABLE_TRADING=1
ROBINHOOD_CHAIN_PRIVATE_KEY=0x...
```

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

| Tool | What it does |
|---|---|
| `get_my_portfolio` | This wallet's ETH, USDG, and Stock Token positions. Read-only. |
| `get_swap_quote` | Quote a Uniswap swap without signing. Read-only. |
| `execute_swap` | **Guarded.** Preview → `confirm: true` → broadcast. Spend-capped. |
| `transfer_usdg` | **Guarded.** Preview → `confirm: true` → broadcast. Spend-capped. |

See [**Safety model**](docs/safety.html) 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.

```bash
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`](.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`](../hood402) USDG-on-Robinhood-Chain x402
rail once it exists. Every tool this package ships today stays free regardless.

## Development

```bash
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](https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json).
  Submit with the [`mcp-publisher`](https://github.com/modelcontextprotocol/registry) 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](LICENSE).

More