spectre-terminal-mcp

An MCP server that lets an AI agent — Claude Code, Claude Desktop, Cursor, any MCP client — read market data from a running Spectre Terminal on the same machine, and trade through it. Thin, stdio; built on the spectre-terminal Python client.

pip install spectre-terminal-mcp

Setup

Switch the Local API on in the terminal (Settings App → General → Local API) and copy the token. Then register the server with your client:

Claude Code:

claude mcp add spectre-terminal -e SPECTRE_LOCAL_API_TOKEN=spt_… -- spectre-terminal-mcp

Claude Desktop (claude_desktop_config.json), Cursor and others:

{
  "mcpServers": {
    "spectre-terminal": {
      "command": "spectre-terminal-mcp",
      "env": { "SPECTRE_LOCAL_API_TOKEN": "spt_…" }
    }
  }
}

The server finds the port through the terminal's instance.json and reads the token from the environment only. It starts even when the terminal is not running; the first tool call then answers terminal_unreachable.

Tools

Read tools are read-only and idempotent and say so in their annotations; the ten trading tools, the ten workspace commands and update_settings are annotated as destructive, so an MCP client may ask the user before each call. Trading answers mean "accepted by the terminal", not "filled": the outcome is read from open_orders and recent_fills. Prices and sizes are decimal strings; times are UTC milliseconds plus an ISO twin. Errors start with a stable code (unauthorized, not_found, unsupported, rate_limited, terminal_unreachable, …) followed by a human message. See docs/mcp.md.

Development

cd mcp
python3 -m venv .venv
.venv/bin/pip install -e ../python -e '.[dev]'
.venv/bin/pytest -q
SPECTRE_LOCAL_API_TOKEN=spt_… .venv/bin/python examples/smoke.py   # against a running terminal