# signallord-mcp-server

[

![signallord-mcp-server MCP server](https://glama.ai/mcp/servers/KK6BZB/signallord-mcp-server/badges/card.svg)

](https://glama.ai/mcp/servers/KK6BZB/signallord-mcp-server)

MCP server for [Signal Lord](https://signallord.io) — 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

```bash
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](https://signallord.io), then generate a key:

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

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

### 4. Run

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

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

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

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

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