cryptowatch-mcp

Crypto market intelligence as an MCP server. Chaos theory, cross-asset topology, and an LLM orchestrator — plug into Claude Desktop and ask anything about crypto markets.

claude mcp add cryptowatch-mcp python mcp_server.py

"Analyze my portfolio: 50% BTC, 30% ETH, 20% SOL"

"Generate a market report for the investment committee"

"Is the market showing crash signals?"

What It Does

23 MCP tools that give any AI real-time crypto market intelligence:

Analysis (7 tools) — each tool computes data AND interprets it (not just numbers)

Tool	What it computes
analyze_trend	Multi-timeframe trend (1h / 4h / 1d) + ADX + volume confirmation + contextual interpretation
analyze_macro	Cross-asset: ETH/BTC, BTC/Gold, correlations + risk-off analysis
analyze_chaos	Lyapunov exponent + fractal dimension + historical percentile
analyze_topology	Persistent homology (ripser) on 5-asset correlation geometry — H0 + H1
analyze_portfolio	Multi-asset: per-asset trend, correlations, diversification, Kelly Criterion sizing
analyze_sentiment	Binance funding rates + open interest + Fear & Greed Index
analyze_onchain	BTC network stats: hash rate, mempool, transactions, market cap

Multi-Agent (1 tool)

Tool	What it computes
multi_agent_score	3 Python agents (trend, risk, macro) with weighted consensus + risk veto

Risk & Compliance (3 tools)

Tool	What it computes
check_risk	Symbolic rules: stop-loss, max drawdown (inviolable)
check_exposure	Regulatory exposure limits compliance
check_kelly	Kelly Criterion optimal position sizing

Reports (2 tools)

Tool	What it computes
generate_market_report	Full investment committee report with all signals
generate_client_brief	Client-ready summary (technical or non-technical)

Intelligence (4 tools)

Tool	What it computes
get_signal_statistics	Historical percentiles for every signal (data-driven thresholds)
get_crash_history	Past crashes with signal values at each phase
compare_to_history	"Does today look like Oct 2025?" — pattern similarity matching
audit_decisions	Full decision audit trail

Paper Trading (4 tools)

Tool	What it computes
paper_open_position	Open a simulated position with configurable sizing
paper_close_position	Close a position and record P&L
paper_get_portfolio	Current paper portfolio state with live P&L
paper_get_history	Full trade history with performance metrics

Infrastructure (1 tool)

Tool	What it computes
health_check	Server health, exchange connectivity, cache status

4 MCP prompts — ready-made analysis workflows:

Prompt	What it does
market_watch	Real-time market surveillance dashboard
portfolio_review	Full portfolio health check with recommendations
crash_detector	Multi-signal crash probability assessment
multi_agent_debate	3-agent scoring with consensus and risk veto

Every tool is an analyst, not a calculator. All tools return formatted markdown with contextual analysis + raw JSON in a collapsible <details> block.

Zero setup required — data auto-fetches from 4 exchanges (Binance, Bybit, OKX, Kraken) on first use and caches locally.

Example Output

analyze_trend("BTC/USDT")

## BTC/USDT — $67,133.99
**24h**: -0.7% | **7d**: -5.8%

**Sparkline 7d**: ▇▅▆▆▇▇▇▇▆▅▄▄▂    ▁▁▁▁  ▁▂▂ ▂

| Timeframe | Trend | |
|-----------|-------|-|
| 1 hour | BULLISH | 🟢 |
| 4 hours | BEARISH | 🔴 |
| 1 day | BEARISH | 🔴 |

📈 Dead cat bounce? — short-term relief rally in a bearish daily trend.

run_agent_debate("BTC/USDT")

## Multi-Agent Consensus — BTC/USDT ($67,133.99)

| Agent | Signal | Score | Confidence | Reasoning |
|-------|--------|-------|-----------|-----------|
| 🔧 Technical | BEARISH | -0.46 | 55% | 1d bearish, 4h bearish, 1h bullish. ADX 19 — weak trend |
| 🛡️ Risk | CAUTION | +0.05 | 8% | Lyapunov at p56. Kelly < 2% — very low edge |
| 🌍 Macro | NEUTRAL | +0.14 | 19% | danger 0/4. correlation 0.68. TDA panic |

Action: REDUCE_50 | Position: 50% | Confidence: 28% | Convergence: SPLIT

calculate_position_size("BTC/USDT")

## Position Sizing — BTC/USDT

| Metric | Value |
|--------|-------|
| Win rate | 48.9% |
| Avg win | 0.36% |
| Avg loss | 0.35% |

Full Kelly: 0.0% | Half Kelly: 0.0% | Risk Parity: 10.0%
Recommended: 0.0% — edge too small for Kelly sizing

Charts

Architecture

DATA        4 exchanges (Binance, Bybit, OKX, Kraken) via ccxt → Parquet cache
               │
SIGNALS     Trend (1h/4h/1d + ADX + volume) + Macro (ETH/BTC, BTC/Gold, correlations)
            + Chaos (Lyapunov) + TDA (ripser persistent homology, H0+H1)
            + Sentiment (funding rates, Fear & Greed) + On-chain data
               │
AGENTS      Multi-agent scoring: 3 Python agents (trend, risk, macro)
            → weighted consensus + risk veto
               │
SKILLS      5 active skills (markdown + live Python enrichment)
            market-analysis · crash-detection · position-management
            cross-asset · chaos-topology
               │
DECISION    Claude orchestrator (23 tools + 4 prompts + skills + market journal)
            Routing: trend → if concerning → macro → if dangerous → TDA
               │
PAPER       Paper trading engine with persistent state + P&L tracking
               │
SAFETY      Symbolic risk rules (inviolable, override everything)
               │
OUTPUT      Markdown tables + emoji + sparklines + JSON

Installation

# From PyPI (coming soon)
pip install cryptowatch-mcp

# From source
git clone https://github.com/Thibbeer/cryptowatch-mcp.git
cd cryptowatch-mcp
pip install -e ".[tda]"

Docker

docker compose up

As MCP server (recommended)

claude mcp add cryptowatch-mcp python mcp_server.py

CLI

cryptowatchwatch BTC/USDT                    # quick market check
cryptowatchbacktest run BTC/USDT             # run backtest
cryptowatchanalyze run                       # LLM orchestrator (needs ANTHROPIC_API_KEY)

Skills System

The orchestrator loads domain expertise on-demand from markdown files, enriched with live Python computation:

Skill	What it loads	Live enrichment
market-analysis	Trend interpretation guide	+ current price, trend, funding rate
crash-detection	Real crash patterns	+ live crash signal assessment (X/5 active)
position-management	Gradual entry/exit rules	+ current trend + funding context
cross-asset	Correlation interpretation	+ live correlation matrix + danger score
chaos-topology	Lyapunov & TDA guide	+ live percentiles + TDA regime

Follows Anthropic's "just-in-time context" pattern.

Tests

pytest tests/ -v

90 tests across 10 suites: trend, macro, chaos, TDA (with ripser), risk rules, MCP tools, paper trading, multi-agent, on-chain, Kelly Criterion.

Tech Stack

Tool	Role
Polars	Dataframes (not pandas)
ccxt	Crypto exchange data (Binance, Bybit, OKX, Kraken)
ripser	Persistent homology (H0 + H1)
MCP SDK	Model Context Protocol server (tools + prompts)
Anthropic SDK	Claude orchestrator
scipy	Scientific computing
typer + rich	CLI
SQLite	Event store + paper trading state
Docker	Containerized deployment

What Makes This Different

1. MCP server — not a bot, a platform. Any AI can use these tools.
2. Real TDA — persistent homology with ripser (H0 + H1), not just correlation numbers
3. Chaos theory — Lyapunov exponent + fractal dimension, data-driven percentile thresholds
4. Active skills — markdown instructions + live Python enrichment (Anthropic 2026 pattern)
5. Every tool interprets — not just numbers, but "this is at p95, historically rare"
6. Zero setup — auto-fetch, auto-cache, plug and play
7. Multi-agent scoring — 3 Python agents with weighted consensus + risk veto (not LLM role-play)
8. Paper trading — persistent state, full P&L tracking, trade history
9. ADX + volume confirmation — trend engine uses ADX strength + volume to filter false signals
10. Kelly Criterion — optimal position sizing based on edge and variance
11. On-chain data — hash rate, mempool congestion, network activity

License

MIT