Metadata-Version: 2.4
Name: crypto-sentiment-x402-mcp
Version: 0.1.4
Summary: MCP server for real-time crypto sentiment as a pay-per-call x402 tool on Base: 9 crypto news RSS outlets plus the Fear & Greed Index, scoring only headlines from the last 72 hours and returning the headlines behind each score.
Author: whatevercat-creator
License-Expression: MIT
Project-URL: Repository, https://github.com/whatevercat-creator/crypto-sentiment-x402
Project-URL: Homepage, https://github.com/whatevercat-creator/crypto-sentiment-x402
Keywords: mcp,x402,crypto,sentiment,agents
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE-MCP
Requires-Dist: mcp<3,>=2.2.0
Requires-Dist: cdp-sdk
Requires-Dist: x402[httpx]>=0.1.0
Requires-Dist: httpx
Requires-Dist: pydantic>=2
Dynamic: license-file

# MCP server

mcp-name: io.github.whatevercat-creator/crypto-sentiment-x402

The `crypto_sentiment_x402_mcp` package exposes the sentiment API as MCP
tools (`crypto_sentiment` for the current reading, `get_hourly_history` for
past hourly readings, plus three free info tools) so Claude Desktop, Claude
Code, or any other MCP client can call it directly as part of an agent's
normal tool use — no separate HTTP client code needed on the caller's side.

**What it returns:** sentiment for a ticker symbol (e.g. BTC, ETH, SOL) from
9 crypto news RSS outlets (CoinDesk, Cointelegraph, Decrypt, Bitcoin
Magazine, The Block, CryptoSlate, NewsBTC, CryptoPotato, The Defiant) and the
Fear & Greed Index. Only headlines from the last 72 hours are scored,
weighted toward the newest. Each call returns a bullish/bearish/neutral
label (or "insufficient recent news"), a compound score, a per-source
breakdown and the headlines behind each score.

**Payment model:** the MCP server itself holds a wallet (via Coinbase
Developer Platform) and pays the API's x402 price out of that wallet for
every call, entirely inside your own local process — invisible to the MCP
protocol layer, so it works in Claude Desktop (or any other stock MCP
client) exactly like a normal, unpaid MCP server would. The paid reading
has no free tier — whoever runs this MCP server funds the wallet it uses.
If you're handing it to someone else to run, they fund their own wallet,
not you.

## Try it free

Three tools need no wallet, no CDP key and pay nothing. The server starts
without any CDP variables, so you can install it and try these first:

- `list_supported_coins` — the 24 supported ticker symbols and names
  (the `symbol` inputs of `crypto_sentiment` and `price_quote` are typed as
  this list).
- `archive_coverage` — what the hourly archive holds (`GET /archive`):
  first reading, row counts and missing hours per symbol.
- `price_quote(symbol)` — makes one unpaid request and reads the 402
  payment requirements: price, network, asset and the `payTo` address.

Two tools are paid, from your own CDP wallet in USDC on Base:

- `crypto_sentiment(symbol)` — the current reading, $0.01 per call.
  Unsupported coins and coins with too little recent news are refused and
  not charged.
- `get_hourly_history(symbol, start, end)` — past hourly readings
  (`GET /history/{symbol}`), $0.05 per call. Recorded live and never
  backfilled; `start`/`end` are ISO 8601, default the last 7 days, at most
  30 days per call. The symbol has to be one `archive_coverage` lists as
  logged. Unlogged symbols, invalid ranges and ranges with no readings are
  refused and not charged.

Wallet setup is below.

## 1. Install

```bash
pip install crypto-sentiment-x402-mcp
```

(`uvx crypto-sentiment-x402-mcp` works too, and needs no separate install
step.)

**Don't install this into the same environment as the FastAPI service**
(`requirements.txt`). `mcp>=2` pulls in a much newer `starlette` than
FastAPI 0.115.0 tolerates (`starlette<0.39.0,>=0.37.2`) — mixing the two in
one venv breaks `app/main.py` at import time (`Router.__init__() got an
unexpected keyword argument 'on_startup'`). If you're hacking on this repo
and want both, give the MCP package its own venv:

```bash
python3 -m venv .venv-mcp && source .venv-mcp/bin/activate
pip install -r requirements-mcp.txt cdp-sdk x402
```

## 2. Create a CDP API key and fund a wallet

1. Free account + API key at https://portal.cdp.coinbase.com
2. Pick a network:
   - `testnet` — free Base Sepolia USDC from
     https://docs.base.org/tools/network-faucets, good for trying this out
     with no real money.
   - `mainnet` — real USDC on Base; the wallet needs actual USDC (plus a
     little ETH for gas) before calls will succeed.
3. The wallet is created automatically the first time the server runs
   (named by `CDP_WALLET_NAME`, default `crypto-sentiment-mcp-wallet`) — run
   it once locally and check the logs/tool output for the address it
   prints, then send that address USDC (+ ETH on mainnet) before relying on
   it inside an agent.

## 3. Register it with an MCP client

**Claude Desktop** — add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "crypto-sentiment": {
      "command": "crypto-sentiment-x402-mcp",
      "env": {
        "CDP_API_KEY_ID": "your-key-id",
        "CDP_API_KEY_SECRET": "your-key-secret",
        "CDP_WALLET_NAME": "crypto-sentiment-mcp-wallet",
        "SENTIMENT_API_URL": "https://crypto-sentiment-x402.onrender.com",
        "X402_NETWORK": "testnet"
      }
    }
  }
}
```

(That assumes `pip install crypto-sentiment-x402-mcp` put the console script
on `PATH` for whatever Python Claude Desktop launches with. If you'd rather
not rely on `PATH`, point `command` at the interpreter and
`args: ["-m", "crypto_sentiment_x402_mcp"]`, or, from a repo clone, at
`mcp_server.py` directly, same as before — both still work.)

**Claude Code** — same shape, either via `claude mcp add` or a project
`.mcp.json` with the same `mcpServers` block.

Any other MCP-compatible client works the same way: it just needs a command
to launch the server with those env vars set.

## 4. Use it

Once registered, an agent can call the `crypto_sentiment` tool with a
`symbol` argument (e.g. `BTC`), or `get_hourly_history` with a `symbol` and
optional `start`/`end`, like any other tool — the payment happens
transparently inside the call. If a call returns an `error` field, it's
almost always the wallet needing more funds; the response includes the
paying wallet's address to check.

## Notes

- `SENTIMENT_API_URL` defaults to the hosted deployment; point it at
  `http://localhost:8000` to test against a local `uvicorn app.main:app`
  instead.
- This is a separate process/wallet from `client.py` (a one-off test
  script) — both pay the same API, just for different purposes.

## License

MIT (see `LICENSE-MCP`) — this package only. The rest of this repository,
including the hosted API in `app/`, remains All Rights Reserved under the
root `LICENSE`.
