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 (17)

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 |

* 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