Ran-Vain — Spark × Claude Desktop Bridge

Ask Claude "What is my unrealized P&L?" and get a live, data-driven answer sourced directly from Spark — in under two seconds.

What Is This?

Ran-Vain bridges Spark (a professional ASX trading platform) with Claude Desktop using Anthropic's Model Context Protocol (MCP). Spark delivers live market data via Dynamic Data Exchange (DDE) — a Windows-native protocol that Excel understands but AI systems don't. This project builds a four-layer translation stack so Claude can answer natural language trading questions using live ASX data.

Architecture

Spark (live ASX feed via DDE)
        │
        ▼
dde_client.py       ← polls 6 stocks every 2 seconds
        │
   ┌────┴────┐
   ▼         ▼
Redis      SQLite    ← real-time snapshots + historical data
   └────┬────┘
        ▼
api/main.py          ← 15 authenticated REST endpoints (FastAPI)
        │
        ▼
spark_mcp.py         ← 18 Claude tools (MCP server over stdio)
        │
        ▼
Claude Desktop       ← natural language query interface

Prerequisites

• Windows 10 or 11 (DDE is Windows-only)
• Spark — installed and logged in
• Python 3.11 — python.org/downloads
• Claude Desktop — claude.ai/download
• Docker Desktop — for Redis

Installation

Step 1 — Virtual environment

cd D:\spark-dde-bot
python -m venv venv
venv\Scripts\Activate.ps1

Step 2 — Dependencies

pip install pywin32 redis loguru python-dotenv fastapi uvicorn httpx mcp

Step 3 — Configure `.env`

REDIS_URL=redis://localhost:6379/0
SQLITE_PATH=dde_listener/spark_data.db
API_BASE=http://localhost:8000
API_KEY=your-strong-api-key-here
DDE_POLL_MS=2000

Step 4 — Start Redis

docker-compose up -d

Step 5 — Seed dummy data (first run only)

python seed_dummy_data.py

Step 6 — Start the DDE listener (open Spark first)

python dde_listener\dde_client.py

Step 7 — Start the API

uvicorn api.main:app --port 8000 --reload

Step 8 — Register MCP with Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "spark-trader": {
      "command": "D:\\spark-dde-bot\\venv\\Scripts\\python.exe",
      "args": ["D:\\spark-dde-bot\\mcp_server\\spark_mcp.py"],
      "env": {
        "API_BASE": "http://localhost:8000",
        "API_KEY": "your-strong-api-key-here"
      }
    }
  }
}

Step 9 — Restart Claude Desktop

Fully close and reopen Claude Desktop. The hammer icon in the toolbar confirms the MCP server is connected.

Startup Checklist

Project Structure

D:\spark-dde-bot\
├── .env                          # Secrets and config (never commit this)
├── claude_desktop_config.json    # Claude Desktop MCP registration
├── docker-compose.yml            # Redis container
├── seed_dummy_data.py            # One-time dummy data seeder
│
├── dde_listener/
│   ├── dde_client.py             # DDE → Redis/SQLite listener
│   ├── spark_data.db             # SQLite database
│   └── logs/                     # Rotating logs (7-day retention)
│
├── api/
│   └── main.py                   # FastAPI — all 15 endpoints
│
├── mcp_server/
│   └── spark_mcp.py              # MCP server — 18 Claude tools
│
└── venv/                         # Python 3.11 virtual environment

API Endpoints

All endpoints require the X-API-Key header. Full docs at http://localhost:8000/docs.

Claude Tools (18)

Example Queries

"Show my open positions"
"What is my P&L today?"
"Which stocks are up today?"
"Show my BHP orders this month"
"What is my portfolio exposure?"
"What was my best trading day?"
"What is my drawdown this week?"
"Which stock has the most volume?"
"Summarise my month and tell me my biggest risk"

Security

• API key authentication on every endpoint via X-API-Key header
• FastAPI binds to localhost:8000 only — not network-exposed by default
• All secrets stored in .env — nothing hardcoded
• All endpoints are read-only GET — no write operations

Before production: change the API key to a strong random value (32+ characters), add .env to .gitignore, enable Redis password auth, and add HTTPS via nginx if exposing beyond localhost.

Known Limitations

Troubleshooting

Tech Stack

Roadmap

• Replace dummy positions/P&L with live broker API or CSV export
• Register dde_client.py as a Windows Service for auto-start and crash recovery
• Read watchlist symbols from a config file or database table
• Use Spark's Watchlist DDE topic to query all symbols in a single DDE call
• Add price alert monitoring that Claude can query
• Expand beyond 6 ASX symbols

Ran-Vain is a read-only analytics and query tool. It does not place, modify, or cancel orders.