@shumi-ai/mcp

Shumi crypto trade-intelligence as an MCP server — the same market intelligence the shumi CLI provides, for any MCP client (Claude Desktop, Claude Code, Cursor, agents).

It's a thin wrapper over Shumi's data API: prices, trends, funding rates, sentiment, narratives, market regime, synthesized signals, pair / delta-neutral ideas, real-world assets, holder and wallet tracking, and transcript highlights. All tools are read-only.

Quick start

You need a Shumi API key (shumi_sk_…). Create one at https://shumi.ai.

Claude Desktop / Claude Code

Add to your MCP config (claude_desktop_config.json, or claude mcp add for Claude Code):

{
  "mcpServers": {
    "shumi": {
      "command": "npx",
      "args": ["-y", "@shumi-ai/mcp"],
      "env": {
        "SHUMI_TOKEN": "shumi_sk_your_key_here"
      }
    }
  }
}

Restart the client. The shumi tools (e.g. get_coin_risk, get_market_health, ask_shumi) appear automatically.

Cursor

~/.cursor/mcp.json uses the same command / args / env shape as above.

Plugin directories

This repo also ships plugin.json and mcp.json at its root, so it installs as an Agent Plugin from Cursor's directory and any other client on that standard.

Set SHUMI_TOKEN in your environment before starting the client when you install this way. The Agent Plugins schema takes literal environment values only — it has no placeholder for a secret — so the manifest deliberately omits env rather than shipping a ${SHUMI_TOKEN} string that would be passed through verbatim and fail as an invalid key.

Tools

Typed (deterministic): get_coin_risk, lookup_coin, resolve_coin, get_coin_sentiment, get_coin_historical, get_market_health, get_market_crossing, get_global_market, get_prices, scan_trends, scan_coins, get_market_sentiment, list_narratives, get_narrative, list_categories, get_category, get_funding_momentum, get_funding_alerts, get_regime, get_signal, get_signal_quality, get_pair_suggestions, list_rwa_assets, get_rwa_asset, get_holders, get_wallets, get_futures_signals, get_basket, get_transcripts.

Real-world assets (list_rwa_assets, get_rwa_asset) cover stocks, ETFs, commodities, indices and FX trading as perps on Hyperliquid builder DEXes. They are not crypto tokens — the coin tools will not find them.

Free-form: ask_shumi (natural-language questions — Shumi classifies, fetches, and synthesizes) and search_web.

List-returning tools accept top (keep first N items) and fields (comma-separated keys to keep) to save tokens.

Resources: shumi://capabilities (the data surface) and shumi://billing/tier (your current entitlement).

Configuration

Gating (free / access / pro tiers and pay-per-call) is enforced server-side, exactly as for the CLI — out-of-quota responses come back as a structured error with an actionable hint.

Remote (HTTP)

For a hosted, multi-user deployment:

PORT=8787 SHUMI_MCP_ALLOWED_ORIGINS=https://yourapp.com npm run start:http

Each request authenticates with its own key header; that token is forwarded to the upstream API per request. Endpoint: POST /mcp, health: GET /health.

Connecting from Claude (static_headers)

Claude supports a fixed credential entered as a request header, so no OAuth server is needed. In Add custom connector → request headers, an organisation administrator enters:

x-api-key: shumi_sk_… works too, and so does an Authorization value with the Bearer prefix omitted — an admin types this once by hand, and a mistyped pair fails closed with no error they can see, so all three shapes are accepted. x-api-key wins if both are present, on the grounds that an admin who set it meant it.

Do not put the key in the URL. The MCP authorization spec prohibits access tokens in the URI query string and Anthropic documents a credential in a URL as a security vulnerability — URLs land in server logs, proxies and browser history. The ?shumiToken= / ?config= query forms exist only because Smithery injects session config that way.

One thing to know before buying for a team: a static_headers credential is shared by the organisation, not per user. Everyone connecting through that connector shares one Shumi account, one free-tier allowance and one quota. Per-user metering needs OAuth — see docs/oauth-plan.md.

An unauthenticated call is answered with 200 and an in-band AUTH_REQUIRED error, not 401. That is deliberate: Claude treats a 401 as the start of an OAuth flow, and a server with no authorization server behind it would send the client into a handshake that cannot complete. The 401 path exists but is gated behind SHUMI_MCP_AUTH_SERVER, so it lights up only once there is an authorization server to point at.

The server is stateless. One endpoint serves both protocol revisions:

• 2026-07-28 — no initialize, no Mcp-Session-Id. A request carries its own routing in headers (Mcp-Method, plus Mcp-Name on tools/call) and its protocol envelope in params._meta, so an intermediary can route and meter a call without parsing the body.
• 2025-11-25 and earlier — still served. Old clients keep their initialize handshake, but each exchange is answered by its own instance rather than a session.

Because nothing outlives a request, GET and DELETE (the 2025 session operations) return 405, and the session tunables that used to live here — SHUMI_MCP_SESSION_TTL_MS, SHUMI_MCP_MAX_SESSIONS, SHUMI_MCP_SESSION_SWEEP_MS — are gone. They are safe to delete from any deployment; unset they do nothing. The idle-session reaper they configured existed to stop liveness probes from growing the heap, which cannot happen when no session is kept.

Develop

npm install
npm test                # unit tests (no network)
npm run inspect         # open the MCP Inspector against the stdio server
SHUMI_TOKEN=… npm start # run the stdio server

Deliberately not exposed

Two CLI routes have no MCP tool, both on purpose:

• walkforward — the route exists, but two of its three actions have nothing behind them while Engine B is paused: positions is empty and outcomes holds a single row from 2026-05-28. Shipping it would hand a caller an empty array with no reason attached. It goes in when the engine resumes.
• watch — server-sent events, which do not fit MCP tool semantics.

Everything else in the CLI's typed surface has a tool.