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

Setup

You need credentials — this package never bundles a shared HoodGrow credential, you supply your own 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, issued access — HOODGROW_API_KEY from hoodgrow.com/api-access.

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. Need more sustained throughput? A persistent API key with its own higher limit is available — see hoodgrow.com/api-access.

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