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.

Tools

Tool	Price (x402)	Description
get_catalog	$0.10	Every listed token: price, source, 24h change, corporate-action adjusted supply, DeFi depth, plus catalog-wide pending/recent corporate actions
get_token	$0.05	One token by symbol (e.g. NVDA), same fields, scoped
get_corporate_actions	uses get_token/get_catalog above	Pending + recent corporate actions; pass a symbol to scope, omit for every tracked token
get_defi	$0.05	Every Morpho market a token participates in (loan OR collateral role) plus its Uniswap V3 pools — not just the single best-APY figure in get_catalog/get_token
get_holders	$0.05	Holder-count trend, 24h net supply change (real mint/burn), and top-holder concentration (optional limit, 1-50, defaults to 10)
get_slippage	$0.05	How much a USD-sized trade (side: "buy" | "sell") would move the price, per Uniswap V3 pool — includes bestPoolAddress/bestEffectivePrice picking the best one for you
get_ohlc	$0.05	OHLC price candles for backtesting (interval: "1h" | "4h" | "1d", optional from/to/limit, defaults to the last 30 days). OHLC only, no volume — HoodGrow has no historical trading-volume time series to draw a volume field from
get_base_tokens	$0.05	Base mainnet (chain 8453) B20 native-equity-token registry — a much smaller sibling of get_catalog. Pre-launch: check each token's status before treating it as tradable — "pre_launch" means no price, no DEX liquidity, no holders exist for it yet

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.

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