Metadata-Version: 2.5
Name: bca-mcp
Version: 0.6.3
Summary: Blockchain Academics MCP server + `bca` CLI: crypto news, entity dossiers, market data, proprietary indicators, and academy explainers for AI agents
Project-URL: Homepage, https://blockchainacademics.com
Project-URL: Documentation, https://blockchainacademics.com/crypto-api/docs
Project-URL: Repository, https://github.com/blockchainacademics/bca-mcp-python
Project-URL: Issues, https://github.com/blockchainacademics/bca-mcp-python/issues
Author-email: Blockchain Academics <dev@blockchainacademics.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,blockchain,crypto,llm,mcp,news
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2.0.0,>=1.21.1
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# bca-mcp

The canonical crypto MCP server for AI agents, **Python edition**: 3,800+ editorial articles, 150+ entity dossiers, 38 academy lessons in 8 courses, and live market data, as MCP tools your agent can call natively.

Sibling of [`@blockchainacademics/mcp`](https://www.npmjs.com/package/@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

LLMs hallucinate about crypto. BCA ships ground-truth editorial content with full attribution. Plug this MCP server into Claude Desktop, LangChain, LlamaIndex, Eliza, or any MCP-compatible agent and your model queries the BCA corpus like any other tool, with citations (`cite_url`, `as_of`, `source_hash`) and an honest `meta.status` on every response.

## Install

```bash
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:

```bash
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.

## 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):

```json
{
  "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):

```json
{
  "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

Ten lines via [`langchain-mcp-adapters`](https://github.com/langchain-ai/langchain-mcp-adapters):

```python
import asyncio, os, sys
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from langchain_mcp_adapters.tools import load_mcp_tools

async def main():
    params = StdioServerParameters(
        command=sys.executable, args=["-m", "bca_mcp"],
        env={**os.environ, "BCA_API_KEY": os.environ["BCA_API_KEY"]},
    )
    async with stdio_client(params) as (r, w), ClientSession(r, w) as s:
        await s.initialize()
        tools = await load_mcp_tools(s)   # -> list[StructuredTool]
        print(await tools[0].ainvoke({"query": "stablecoin regulation"}))

asyncio.run(main())
```

Full worked example in [`examples/langchain_agent.py`](./examples/langchain_agent.py). Raw MCP client loop (no LangChain) in [`examples/generic_agent.py`](./examples/generic_agent.py).

## Use from Eliza

See [`examples/eliza_plugin.md`](./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.

```bash
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:

```json
{
  "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`.** This is the core trade: BCA gives agents ground-truth citations; agents give BCA distribution. `as_of` and `source_hash` let downstream systems detect staleness and verify content integrity. 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):

```json
{ "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 this is the answer on 88 of the 105 tools; the message includes the signup URL. |
| `BCA_RATE_LIMIT` | Rate limit exceeded (HTTP 429; honor `Retry-After`) |
| `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 |
| `BCA_UNKNOWN` | Unexpected error inside the server (the process keeps running) |

## Development

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

Run the server directly for debugging:

```bash
BCA_API_KEY=... python -m bca_mcp
```

## Getting help

- **Questions:** ask in [GitHub Discussions Q&A](https://github.com/blockchainacademics/bca-mcp/discussions/categories/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](https://github.com/blockchainacademics/bca-mcp-python/issues).
- **Account and billing:** email [support@blockchainacademics.com](mailto:support@blockchainacademics.com).
- **Security reports:** email [security@blockchainacademics.com](mailto: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](https://github.com/blockchainacademics/bca-mcp/discussions/15).

## Contributing

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

## License

MIT © 2026 Blockchain Academics
