signallord-mcp-server

MCP server for Signal Lord — know which Bitcoin regime you're in and the probabilities of what happens next.

Not another price feed. Signal Lord tells AI agents where Bitcoin is in its market cycle, what similar periods looked like historically, and what usually happens next — backed by 20+ real-time indicators and pattern matching against documented cycle history.

Quick Start

1. Install

npm install -g signallord-mcp-server

Requires Python 3.10+ with pip on your PATH. Dependencies install automatically.

2. Get an API Key

Sign up at signallord.io, then generate a key:

# After logging in, via the API:
curl -X POST https://signallord.onrender.com/api/keys/generate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "my MCP key"}'

Save the returned sk-sl-... key — it's shown only once.

3. Configure

export SIGNALLORD_API_KEY=sk-sl-your-key-here
export SIGNALLORD_API_BASE_URL=https://signallord.onrender.com

4. Run

signallord-mcp

Server starts on http://localhost:8100 (streamable HTTP transport).

5. Connect to Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "signallord": {
      "command": "signallord-mcp",
      "env": {
        "SIGNALLORD_API_KEY": "sk-sl-your-key-here",
        "SIGNALLORD_API_BASE_URL": "https://signallord.onrender.com"
      }
    }
  }
}

Or connect via URL:

{
  "mcpServers": {
    "signallord": {
      "url": "http://localhost:8100/mcp"
    }
  }
}

What You Get

The question every trader asks: "What's Bitcoin doing right now and what happens next?"

Signal Lord answers with regime detection, not price predictions:

Instead of...	Signal Lord gives you...
"BTC is $84,000"	"Bitcoin is in a High Vol Chop regime, similar to March 2025 tariff volatility"
"Fear & Greed is 45"	"35% chance of consolidation, 30% chance of V-recovery based on 4 similar historical periods"
"ETF flows were +$200M"	"Institutional score 6.2/10 — steady accumulation but not FOMO. Pattern matches post-halving 2024 buildup"

Tiers & Rate Limits

Tier	Regime Detail	Rate Limit	Data
Free	Regime + probabilities + top match name	10/min, 500/day	4 gauges + basic market data
Premium	Full historical matches + catalysts + feature vectors	30/min, 2000/day	All 8 gauges + ETF/on-chain + Odin AI
Pro	Everything + signals	60/min, 5000/day	Full platform access

Tools (26)

Regime Detection (flagship)

Tool	Tier	Description
signallord_get_regime	Free*	Current regime, historical matches, outcome probabilities
signallord_get_regime_history	Free	Regime evolution over time from daily snapshots

Gauges

Tool	Tier	Description
signallord_get_composite_score	Free	Composite 0-100 score with regime label
signallord_get_gauge_breakdown	Free*	Individual gauge scores (4 free, 8 premium)
signallord_get_gauge_history	Free	Historical scores for trend analysis

Odin AI

Tool	Tier	Description
signallord_get_odin_analysis	Free*	AI market analysis (basic free, enriched premium)
signallord_ask_odin	Premium	Ask Odin a question about BTC markets

Market Data

Tool	Tier	Description
signallord_get_btc_metrics	Free*	Price, volume, derivatives (+ on-chain on premium)
signallord_get_institutional_data	Premium	ETF flows, Coinbase premium, CME basis
signallord_get_macro_indicators	Free	DXY, VIX, Fear & Greed, liquidity stack
signallord_get_what_changed	Free	Day-over-day market changes

Signals & Analytics

Tool	Tier	Description
signallord_get_btc_vix_correlation	Premium	BTC vs VIX correlation + spike detection
signallord_get_btc_gold_ratio	Premium	BTC vs Gold normalized comparison
signallord_get_etf_flow_history	Premium	Daily ETF flow history (since Jan 2024)
signallord_get_exchange_flow_history	Premium	Exchange flow accumulation/distribution
signallord_get_liquidation_data	Free	Liquidation momentum scoring
signallord_get_odin_track_record	Free	AI prediction accuracy and learned patterns

Cycle Indicators (v1.2.0)

Tool	Tier	Description
signallord_get_pi_cycle	Premium	111DMA vs 350DMA·2 cross — cycle-top warning
signallord_get_realized_price	Premium	Spot vs on-chain cost basis + reclaim/loss events
signallord_get_reserve_risk	Premium	Price/HODL Bank ratio banded into cycle phases
signallord_get_mtf_trend	Premium	D/W/M trend alignment composite (-3 to +3)
signallord_get_hash_ribbons	Premium	30/60-day hashrate MA cross + 30d divergence z-score
signallord_get_capitulation_score	Premium	Composite of volume, liquidations, funding, OI, velocity

Probability Playbooks (v1.2.0)

Tool	Tier	Description
signallord_get_cycle_bottom_probability	Premium	Weighted accumulation playbook score (0-100)
signallord_get_cycle_top_probability	Premium	Weighted distribution playbook score (0-100)

Meta (v1.2.0)

Tool	Tier	Description
signallord_get_data_health	Free	Which signals are currently stale due to upstream data issues

* Returns limited data on free tier, full data on premium.

Example: Regime Detection Response

{
  "regime": "high_vol_chop",
  "regime_label": "High Vol Chop",
  "regime_confidence": 0.72,
  "regime_duration_hours": 168.5,
  "most_likely_outcome": "consolidation",
  "most_likely_outcome_label": "Consolidation — went sideways for weeks",
  "most_likely_probability": 40.0,
  "outcome_probabilities": {
    "consolidation": 40.0,
    "v_recovery": 30.0,
    "reversal": 20.0,
    "correction": 10.0
  },
  "expected_move_pct": -2.5,
  "expected_timeframe_days": 35,
  "most_similar": {
    "name": "March 2025 Tariff Volatility",
    "date_range": "2025-03 to 2025-04",
    "similarity": 0.89,
    "outcome_description": "Oscillating as market digests policy uncertainty."
  },
  "historical_matches": ["...3 most similar periods with full details..."]
}

Environment Variables

Variable	Default	Description
SIGNALLORD_API_KEY	(empty)	Your sk-sl-... API key
SIGNALLORD_API_BASE_URL	http://localhost:8000	Signal Lord backend URL
MCP_SERVER_PORT	8100	Server listen port

Testing

# Syntax check
python -m py_compile server.py

# Tier verification (against production)
SIGNALLORD_PREMIUM_KEY=sk-sl-xxx python test_tiers.py

# MCP Inspector
npx @modelcontextprotocol/inspector

Architecture

AI Agent (Claude, Cursor, etc.)
    | MCP Protocol (Streamable HTTP)
    v
signallord-mcp-server (port 8100)
    | HTTP + X-SIGNALLORD-API-KEY header
    v
Signal Lord backend API
    | Regime Detection + Historical Pattern Matching
    | 20+ real-time indicators + 8 data sources
    v
PostgreSQL + Odin AI + Pattern Database

The MCP server is a stateless protocol adapter. All data, auth, rate limiting, and regime detection is handled by the backend.

License

MIT