hoodgrow-mcp

MCP (Model Context Protocol) server for the HoodGrow Robinhood Chain stock token API — live price, corporate-action adjusted supply (ERC-8056, correct through stock splits), Morpho/Uniswap DeFi depth, corporate actions (splits, dividends), holder analytics, trade price-impact/slippage estimates, OHLC price candles for backtesting, market movers, a large-trade ("whale") feed, and a Base mainnet B20 native-equity-token registry, exposed as tools for any MCP client (Claude Desktop, Claude Code, etc). Built on the hoodgrow SDK — pays per call via x402 (USDC on Base) or uses a bearer API key, your choice.

Fastest: the hosted server (no install, no key)

HoodGrow runs the MCP server for you at https://www.hoodgrow.com/api/mcp. Every tool is read-only, so you can point an assistant at it and start asking with no install, no signup, no key:

claude mcp add --transport http hoodgrow https://www.hoodgrow.com/api/mcp

or in mcp.json / claude_desktop_config.json:

{
  "mcpServers": {
    "hoodgrow": { "type": "http", "url": "https://www.hoodgrow.com/api/mcp" }
  }
}

Then ask your assistant things like:

• "What's the corporate-action adjusted supply and 24h volume for NVDA on Robinhood Chain?"
• "Any pending stock splits or dividends in the next week?"
• "Top gainers and biggest whale trades today."

Anonymous access is bounded per IP — 20 requests/minute and 30 daily units, where a full-catalog call costs 10 units and a single-symbol call costs 1. Enough to work through a conversation; a free API key (below) raises the ceiling to 40 units and gives you a budget nobody else behind your IP can spend. Prefer running the server yourself, or need x402 pay-per-call? Use the npm package instead:

Run it yourself (npm — your own credentials)

You supply your own credentials — this package never bundles a shared HoodGrow credential, so you control what gets spent and who's billed. Pick one:

• x402, pay per call, no signup — a wallet private key (HOODGROW_PRIVATE_KEY), funded with USDC on Base. $0.10/call for the full catalog, $0.05/call for one token.
• API key, free, self-serve — HOODGROW_API_KEY from hoodgrow.com/profile.

Claude Desktop / Claude Code

Add to your MCP config (Claude Desktop: claude_desktop_config.json; Claude Code: claude mcp add):

{
  "mcpServers": {
    "hoodgrow": {
      "command": "npx",
      "args": ["-y", "hoodgrow-mcp"],
      "env": {
        "HOODGROW_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Or with an API key instead:

{
  "mcpServers": {
    "hoodgrow": {
      "command": "npx",
      "args": ["-y", "hoodgrow-mcp"],
      "env": {
        "HOODGROW_API_KEY": "..."
      }
    }
  }
}

Never hardcode a real private key in a committed config file — only fund that wallet with what you're willing to spend on this API.

Optionally, once you've bought a credit balance with the buy_credits tool, add "HOODGROW_USE_CREDITS": "true" alongside HOODGROW_PRIVATE_KEY to have every data tool spend that balance (a cheap wallet signature) instead of paying x402 per call. See "Prepaid credits" below.

Tools

Each call returns the API's JSON response as the tool's text content. A failed request (unknown symbol, server error) comes back as an MCP tool error (isError: true) rather than crashing the server.

Prepaid credits

Buy a dollar-denominated credit balance once via x402 (buy_credits), then set HOODGROW_USE_CREDITS=true (alongside HOODGROW_PRIVATE_KEY) and restart the server: every data tool above then spends the balance with a cheap, gas-free wallet signature instead of a fresh on-chain x402 payment per call. list_credit_bundles/get_credit_balance never spend anything; only the metered data tools (get_catalog, get_token, etc.) and buy_credits itself move money.

Payment safety

x402 payments are real money and are not idempotent — a retried timed-out call can pay twice. HoodGrow's paywall only ever asks for USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) on Base mainnet (eip155:8453), paid to 0x8520B3693a2Cf3c2bEa3a505Af3A9c1b093954c7, capped at $0.10/call — the underlying hoodgrow/@x402 dependencies handle protocol-level verification, but you're responsible for how much you fund the signing wallet with.

Rate limits

30 requests/minute per IP by default for pay-per-call use.

With a free API key, the daily allowance is 40 units and is weighted by what a call returns, not by how many calls you make:

So prefer get_token over get_catalog when you want one symbol — it is ten times cheaper against the allowance and returns less to parse.

x402 pay-per-call has no daily cap at all ($0.10 for the catalog, $0.05 per symbol), and Builder removes the cap and raises the per-minute limit to 300 — see docs.hoodgrow.com.

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (mocked fetch + real in-memory MCP client/server, no network)

License

MIT