@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.
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_unlocks, get_unlock_calendar, 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
| Env var | Default | Purpose |
|---|
SHUMI_TOKEN | — | API key (shumi_sk_*). Required. |
SHUMI_API_URL | production coinrotator-ai endpoint | Override the API base URL. |
SHUMI_WALLET | — | Wallet address to include in NLP query context. |
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.
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:
| field | value |
|---|
| URL | https://mcp.shumi.ai/mcp |
| Header name | Authorization |
| Header value | Bearer shumi_sk_… |
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
npm run inspect
SHUMI_TOKEN=… npm start
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.