Blockchain Academics MCP server

bca-mcp

Python edition of the Blockchain Academics crypto MCP server for AI agents: cited news, prices, onchain data, sentiment and indicators. 3,800+ editorial articles, about 150 entity dossiers, 38 academy lessons in 8 courses and live market data, as MCP tools your agent can call.

Sibling of @blockchainacademics/mcp (TypeScript). Same REST API. Same attribution contract. Use whichever fits your stack.

v0.6 ships the full 105-tool catalog plus the bca CLI. The tool names match the TypeScript package one for one, and the CLI gives you a terminal-first way to explore the same API.

Why

Every answer says where it came from and how complete it is. attribution.citations[] lists the sources, primary source first (cite_url, as_of, source_hash), and meta.status says whether the answer is complete, partial, stale or unseeded. An agent can cite each fact and tell a full answer from a thin one. The server works in Claude Desktop, LangChain, LlamaIndex, Eliza and any other MCP client.

Not financial advice

The tools return data, analysis and their sources. Nothing they return is financial, investment or tax advice, or a recommendation to buy or sell anything.

Install

pip install bca-mcp
# or, isolated:
pipx install bca-mcp
# or, ephemeral:
uvx bca-mcp

Zero-config first run (no API key needed)

uvx bca-mcp works out of the box. The package ships with a public demo key, and 17 tools work without a key of your own:

get_price, get_trending, get_fear_greed, get_market_overview, search_news, get_article, get_sentiment, get_entity (slug form), get_explainer, get_recent_stories, get_topic, search_grants, get_grant, list_jobs, get_job, search_academy, get_as_of_snapshot.

Every other tool answers without a key with a clean upgrade message (BCA_TIER_LOCKED) that links the free signup. The demo key is shared: 100 calls a day across all demo users, 20 a day per IP address, 1 per second. On startup the server prints a one-time banner on stderr while demo mode is active.

Configure an API key

Get a free API key at https://blockchainacademics.com/crypto-api/signup (2,000 calls/month per user). A free key opens 52 tools. Paid plans open the rest, such as agent-backed research generation, crypto Twitter intelligence and the proprietary indicators, and raise the rate limits; each tool's description names its tier when it is not free.

Set the env var before launching the server:

export BCA_API_KEY="bca_live_xxxxxxxxxxxxxxxx"
# optional: override the default https://api.blockchainacademics.com
export BCA_API_BASE="https://api.blockchainacademics.com"
# BCA_API_BASE_URL is also accepted as a legacy alias

When BCA_API_KEY is set, the demo banner is suppressed and your key's plan decides which tools answer: 52 on a free key, the rest on paid plans. When it's unset, every response carries meta.tier: "demo" and meta.upgrade_url so your agent can detect the demo path.

Privacy

• Each tool call sends its arguments (for example a search phrase, a coin name, or a wallet or contract address you ask about) and your key, if you set one, over HTTPS to api.blockchainacademics.com, our own API, or to the staging or local base you set in BCA_API_BASE. The server sends nothing to any other host; monitor_keyword only looks up the webhook's host name in DNS to refuse private addresses.
• The MCP server stores nothing on your computer. The bca CLI keeps your key in ~/.bca/config.toml (readable only by you) after bca login. The API counts calls per key per day and does not log request bodies or query parameters that could contain personal data.
• Full policy, retention and your rights: blockchainacademics.com/privacy, section 12 (Crypto API and MCP Server). Privacy requests: privacy@blockchainacademics.com.

Use from Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json).

Zero-config demo path (no API key needed):

{
  "mcpServers": {
    "blockchainacademics": {
      "command": "python",
      "args": ["-m", "bca_mcp"]
    }
  }
}

With your own key (a free key from blockchainacademics.com/crypto-api/signup opens 52 tools; paid plans open the rest):

{
  "mcpServers": {
    "blockchainacademics": {
      "command": "python",
      "args": ["-m", "bca_mcp"],
      "env": { "BCA_API_KEY": "bca_live_xxxxxxxxxxxxxxxx" }
    }
  }
}

Restart Claude Desktop and the tools appear in the tool picker. If you installed via pipx, you can swap "command": "bca-mcp" with empty args (a console-script entry point is registered by the package).

Every tool carries MCP annotations: a readable title, readOnlyHint: true on the read tools, and readOnlyHint: false on the eight tools that create a record or start a job (submit_listing, book_kol_campaign, request_custom_research, monitor_keyword, generate_due_diligence, generate_tokenomics_model, summarize_whitepaper, translate_contract), so clients can ask before running those.

Use from LangChain

LangChain ships MCP support as langchain.mcp (beta, pip install "langchain[mcp]>=1.4.0"; it replaces the archived langchain-mcp-adapters). MCPAdapter starts the server and turns its tools into LangChain tools:

import asyncio, os
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter

config = {
    "mcpServers": {
        "bca": {
            "command": "uvx",
            "args": ["bca-mcp"],
            "env": {"BCA_API_KEY": os.environ.get("BCA_API_KEY", "")},
        }
    }
}

async def main() -> None:
    async with MCPAdapter(config) as adapter:
        tools = await adapter.list_tools()
        agent = create_agent("<your chat model>", tools)
        result = await agent.ainvoke(
            {"messages": [("user", "What happened with Ethereum this week? Cite sources.")]}
        )
        print(result["messages"][-1].content)

asyncio.run(main())

An empty BCA_API_KEY runs the 17 tools that need no key. Worked example in examples/langchain_agent.py. Raw MCP client loop (no LangChain) in examples/generic_agent.py.

Use from Eliza

See examples/eliza_plugin.md for integration notes: bca-mcp plugs into Eliza's MCP plugin surface as a stdio-transport server.

The bca CLI

pip install bca-mcp also registers a terminal-first CLI. It talks to the same REST API as the MCP server, which makes it handy for debugging, quick lookups, and shell pipelines.

bca login                                # store API key in ~/.bca/config.toml (chmod 600)
bca news search "bitcoin etf" -n 5       # recent articles, rich table + links
bca entity ethereum                      # dossier panel
bca price bitcoin,ethereum,solana        # spot + 24h change table (CoinGecko ids)
bca market overview -n 10                # top-N by market cap
bca indicator coverage-index bitcoin -w 30d
bca explainer defi-fundamentals          # a course or a lesson, rendered markdown
bca agent summarize-whitepaper --url https://bitcoin.org/bitcoin.pdf
bca version                              # CLI + live API version

Every command accepts --json for unformatted output suitable for jq pipelines. Env vars (BCA_API_KEY, BCA_API_BASE) take precedence over ~/.bca/config.toml.

Tool catalog (a selection; all 105 at https://blockchainacademics.com/crypto-api/tools)

Tool	Category	Endpoint	Tier	Without a key
search_news	content	GET /v1/articles/search	Free	yes
get_article	content	GET /v1/articles/{slug}	Free	yes
get_entity	content	GET /v1/entities/{slug}	Free	yes
list_entity_mentions	content	GET /v1/entities/{slug}/mentions	Free	no
list_topics	content	GET /v1/topics	Free	no
get_explainer	content	GET /v1/academy/{slug}	Free	yes
get_price	market	GET /v1/market/price	Free	yes
get_market_overview	market	GET /v1/market/overview	Free	yes

All eight work with a free API key. "Without a key" marks the ones open in demo mode.

Tool details

search_news

Required: query (1–512 chars). Optional: entity, ticker, since (ISO 8601), topic, limit (1–50, default 10), offset (paging).

get_article

Required: slug (1–240 chars).

get_entity

Required: exactly one of slug (e.g. "vitalik-buterin") or ticker (e.g. "ETH", case-insensitive). Aliases in slug form resolve to the canonical entity (cz → changpeng-zhao, maker → makerdao, bsc → bnb-chain), and the answer names the alias in resolved_from_alias. The ticker form returns every entity that matches the ticker and needs an API key; the slug form works without one.

list_entity_mentions

Required: slug (entity). Optional: since (ISO 8601), limit (1–100, default 50), offset (paging).

list_topics

No arguments.

get_explainer

Required: exactly one of slug (a course slug such as "defi-fundamentals" returns the course and its lessons; a lesson slug such as "decentralized-exchanges" returns the lesson text) or topic (keyword, e.g. "defi").

get_price

Required: ids (comma-separated CoinGecko IDs, e.g. "bitcoin,ethereum", not exchange tickers). Optional: vs (quote currency, default usd).

get_market_overview

Optional: limit (1–100, default 20).

Attribution contract

Every response is the same envelope, with a structured attribution block:

{
  "data": { ... },
  "attribution": {
    "citations": [
      {
        "cite_url": "https://www.coingecko.com/en/coins/bitcoin",
        "as_of": "2026-11-01T12:34:56Z",
        "source_hash": "sha256:..."
      }
    ]
  },
  "meta": {
    "status": "complete",
    "request_id": "req_...",
    "pageInfo": { "hasNextPage": false, "hasPreviousPage": false, "startCursor": null, "endCursor": null }
  }
}

attribution.citations[0] is the primary source: the upstream page the data came from when there is one (an article's publisher, CoinGecko, DefiLlama, Etherscan), otherwise the BCA page for the record. A BCA link is included only where blockchainacademics.com has a page for the data; when there is neither, the one citation points at the tool's entry in the API reference.

When your agent surfaces BCA content to a user, link citations[0].cite_url. as_of and source_hash let downstream systems spot stale or changed data. Fields are preserved as null (not dropped) when upstream omits them, so agents can detect missing provenance explicitly.

The MCP server returns data inside an <untrusted_content source="bca-api"> fence so the host model reads upstream text as data, not instructions. attribution and meta stay structured.

Reading meta.status

The API says how complete each answer is. The MCP server passes every status through as a successful tool response, so your agent sees it and decides how to surface it:

meta.status	Meaning	meta.diagnostic
complete	The answer the tool promises.	absent
partial	Data is returned, but some of it is missing or defaulted.	missing names what is absent (when an upstream source failed: vendor and upstream_status instead)
stale	Data is returned, but it is older than the tool promises.	as_of (when the data was produced) and age_seconds
unseeded	No real data yet: an empty source, placeholder rows, or a feed that is not connected.	reason and eta

diagnostic.reason explains every non-complete answer. Lists that page by offset (search_news, search_grants, list_entities, list_entity_mentions, search_academy) set meta.pageInfo.hasNextPage when more results exist. Several tools usually answer unseeded or partial today, and their descriptions say so (for example get_kol_influence, check_memecoin_risk, get_exchange_flows, the memo and thesis tools, and the X-based tools while the X reader is paused). The legacy integration_pending and upstream_error statuses of older API deploys arrive as unseeded and partial. This matches the TS sibling's behavior.

Errors

The server never crashes the stdio process. Every failed tool call is an MCP tool result with isError: true and a JSON body (a malformed JSON-RPC request, such as arguments that are not an object, gets the MCP SDK's JSON-RPC error instead):

{ "error": { "code": "BCA_BAD_REQUEST", "message": "Invalid arguments for book_kol_campaign: budget_usd: Input should be greater than or equal to 500" } }

Invalid arguments are rejected before any request is sent, with one field: problem pair per issue, separated by ; . When the API itself rejects a request (HTTP 4xx), the message adds the API's explanation (up to 500 characters), fenced as untrusted content. 5xx errors stay generic.

Code	Meaning
BCA_AUTH	Invalid BCA_API_KEY (HTTP 401/403), or a key that cannot be sent as a header value (a line break inside it); the key itself is never repeated in the message
BCA_TIER_LOCKED	Tool not in your current tier's allowlist (HTTP 403 without a key, HTTP 402 with a key on a lower plan). Without a key this is the answer on 88 of the 105 tools; the message includes the signup URL, or the pricing URL for a key on a lower plan.
BCA_RATE_LIMIT	Rate limit exceeded (HTTP 429; honor Retry-After). A read the per-second limit turned away is sent again first, up to twice. The message carries the API's own reason, which names the limit that was hit (up to 500 characters, inside an <untrusted_content> fence).
BCA_UPSTREAM	BCA API returned 5xx or malformed JSON
BCA_NETWORK	Network failure or 20s timeout exceeded
BCA_BAD_REQUEST	Invalid tool arguments, or a 4xx response from the API (other than 401, 402, 403 and 429)
BCA_UNKNOWN	Unexpected error inside the server (the process keeps running)

Development

python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest -q

Run the server directly for debugging:

BCA_API_KEY=... python -m bca_mcp

Getting help

• Questions: ask in GitHub Discussions Q&A. The npm and Python packages share one Q&A, so every answer lives in one place. Search first, since someone may have asked already.
• Bugs: open an issue.
• Account and billing: email support@blockchainacademics.com.
• Security reports: email security@blockchainacademics.com, never a public issue.

Never post a full API key. If we need to know which key, share only the key prefix, the part before the dots on your dashboard (for example bca_1a2b3c4d). Our team will never ask for your key or a seed phrase. Response times by plan are in How to get help.

Contributing

Issues, PRs, and feature requests: https://github.com/blockchainacademics/bca-mcp-python

License

MIT © 2026 Blockchain Academics