Skip to main content
Glama
Shumi AI

Shumi AI

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

Related MCP server: All-in-One Crypto Trading MCP Server

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

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:

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

Available Tools

23 tools
ask_shumiAsk Shumi (free-form)A
Read-only
Inspect

Ask Shumi any crypto-market question in natural language. Shumi classifies the query, fetches the relevant data, and returns a synthesized answer. Use this when no specific typed tool fits, or for multi-part / comparative questions.

Inputs: query (required), archetype.

get_categoryCategory detailA
Read-only
Inspect

Detail for one category. view=info (trend breakdown), coins (member coins), sentiment.

Inputs: name (required), top, view, fields. Returns: data, meta, error

get_coin_historicalCoin historical metadataA
Read-only
Inspect

Historical metadata for a coin (holder cohorts, sentiment and funding history).

Inputs: symbol (required). Returns: data, meta, error

get_coin_riskCoin risk contextA
Read-only
Inspect

Bundled risk context for one or more coins: price, funding APR, deterministic funding_paying_side, funding_receiving_side, carry_if_long and carry_if_short fields, daily/weekly trend, sentiment stance, and BTC correlation. Funding applies to perpetual positions only; spot positions neither pay nor receive it. Relay the carry fields exactly rather than inferring direction from crowding. The best single tool for "should I be worried about X".

Inputs: symbols (required). Returns: data, meta, error

get_coin_sentimentCoin sentimentA
Read-only
Inspect

On-chain/social sentiment aggregates for a single coin.

Inputs: symbol (required). Returns: data, meta, error

get_funding_alertsFunding alertsA
Read-only
Inspect

Discrete funding-rate alert events (asset, trigger zone, funding at trigger, fired-at time).

Inputs: top, fields. Returns: data, meta, error

get_funding_momentumFunding momentumA
Read-only
Inspect

Perpetual funding-rate positioning context, market-wide or for one symbol. APR is already in percent units (1.7 = 1.7%). Positive funding means longs pay and shorts receive; negative funding means shorts pay and longs receive. Funding is context only, not a standalone directional, timing, or entry signal.

Inputs: symbol. Returns: data, meta, error

get_global_marketGlobal market aggregatesA
Read-only
Inspect

Global market aggregates: BTC dominance, total market cap, total volume.

Inputs: no named parameters. Returns: data, meta, error

get_market_healthMarket healthA
Read-only
Inspect

Overall market health: the UP/HODL/DOWN trend distribution and extreme movers. Set context for the full bundle.

Inputs: context. Returns: data, meta, error

get_market_sentimentMarket sentimentA
Read-only
Inspect

Aggregate market sentiment. view=market/latest/summary (overall), narratives, categories, slopes/entity-slopes (what is trending), health (pipeline status).

Inputs: top, view, fields. Returns: data, meta, error

get_narrativeNarrative sentimentA
Read-only
Inspect

Sentiment and momentum for a single named narrative.

Inputs: name (required). Returns: data, meta, error

get_pair_suggestionsPair / delta-neutral suggestionsA
Read-only
Inspect

Pair-trading and delta-neutral funding-arbitrage intelligence. mode=suggestions (pair ideas), delta-neutral (funding arb), history (backtest), signal (state for a specific pair — needs token_a & token_b).

Inputs: top, mode, limit, fields, +5 more. Returns: data, meta, error

get_pricesBulk live pricesA
Read-only
Inspect

Bulk live prices, optionally with 4h/24h/7d baseline overlays. Omit symbols for the full tracked set.

Inputs: top, fields, symbols, baselines. Returns: data, meta, error

get_regimeMarket regimeA
Read-only
Inspect

Market regime signals. view=active (current positions), signals (all), confidence (scores). Provide symbol to get that symbol's regime history instead.

Inputs: view, symbol. Returns: data, meta, error

get_signalSynthesized signalA
Read-only
Inspect

Synthesized verdict for a coin, combining trend, funding, sentiment and regime.

Inputs: symbol (required). Returns: data, meta, error

get_signal_qualitySignal qualityB
Read-only
Inspect

Signal validation envelope for an asset: Sharpe ratio, win rate, sample size, reliability tier.

Inputs: asset (required), signal_type. Returns: data, meta, error

list_categoriesList categoriesA
Read-only
Inspect

List all tracked crypto categories (DeFi, Layer 2, memes, …).

Inputs: top, fields. Returns: data, meta, error

list_narrativesList narrativesA
Read-only
Inspect

List the currently active market narratives (e.g. "AI coins", "DeFi summer").

Inputs: top, fields. Returns: data, meta, error

lookup_coinLook up a coinA
Read-only
Inspect

Look up a single coin and its core metrics (price, trend, metadata) by symbol, name, CoinGecko/internal id, or on-chain contract address.

Inputs: identifier (required), by, chain. Returns: data, meta, error

resolve_coinResolve a coin (fuzzy)A
Read-only
Inspect

Fuzzily resolve a symbol, name, or contract to canonical coin candidates. Use this first when the user input is ambiguous, before calling other tools.

Inputs: query (required), limit. Returns: data, meta, error

scan_coinsScan / filter coinsA
Read-only
Inspect

Filter the tracked universe by trend direction, category, market-cap band, and exchange.

Inputs: top, limit, trend, fields, +5 more. Returns: data, meta, error

search_webSearch the webA
Read-only
Inspect

Search the web for crypto information, or get a direct answer. Backed by Shumi's web-search tool.

Inputs: query (required), answer.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 23 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of crypto market analysis, from global metrics to coin-specific risk, sentiment, funding, signals, and natural language queries. Detailed descriptions prevent ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with lowercase underscores (e.g., get_global_market, scan_trends, list_narratives). No mixing of styles.

    Tool Count5/5

    23 tools cover the broad domain of crypto market data without being overwhelming. Each tool serves a clear purpose and the count is well-scoped for the server's functionality.

    Completeness5/5

    The tool set covers all major areas: market aggregates, individual coins, trends, sentiment, categories, narratives, funding, signals, pairs, and a general query tool. No obvious gaps for the intended use.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Delivers real-time crypto market microstructure, derivatives, order flow CVD/OI regime classification, fear & greed sentiment, and whale tracking context, enabling traders to assess market regimes and complement charting tools.
      54 npm
      MIT