MCP server
Let an AI agent in Claude Code, Claude Desktop or Cursor read the terminal, trade and change the layout.
spectre-terminal-mcp is a Model Context Protocol server that gives an AI
agent a running terminal: market data, the account, trading, the layout and
settings. It runs on your machine and talks to the terminal through the
Local API.
Install
pip install spectre-terminal-mcpThen switch the Local API on in the terminal and copy the token. See Get the token.
Set up the server in your client
claude mcp add spectre-terminal -e SPECTRE_LOCAL_API_TOKEN=spt_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef -- spectre-terminal-mcpThe token above is a sample, so use your own. Claude Desktop keeps this block
in claude_desktop_config.json. Cursor and other clients with a JSON
configuration take the same block.
The server reads the token only from the environment and finds the terminal
by itself. It starts even when the terminal is not running. The first tool
call then answers terminal_unreachable, and the next call looks for the
terminal again.
What an agent can do
| Area | What the agent can do | Changes something |
|---|---|---|
| Status | Check that the terminal runs and list its connections | No |
| Instruments | Find the exact address of a coin or symbol | No |
| Market data | Read the latest price, the top of the order book, a summary of recent trades, volume clusters and candles | No |
| Account | Read balances, positions, open orders, fills and leverage | No |
| Trading | Place and cancel orders and trigger orders, close a position, set leverage and margin mode | Yes |
| Workspace | Read the layout. Open, change and close stacks, tabs and windows | Yes, except reading |
| Settings | Read settings and write them | Yes, except reading |
Every tool with its arguments is listed in the tool reference.
The answers are short summaries made for a model, not raw data. Prices and sizes are decimal strings. Times are UTC milliseconds with an ISO copy next to them.
Tools that only read are marked read-only, so a client can call them without asking you. Tools that trade, change the layout or write settings are marked destructive, so a client may ask you before each call.
There is no live stream. An agent that needs fresh data calls
market_snapshot again. A program that needs live data uses
the stream.
An instrument that is not open in the terminal takes up to 3 seconds on the first call, see The first call.
Trade safely
Real money. The trading tools send real orders to the exchange through the terminal. The server asks for no confirmation of its own. Whether you are asked before a call depends on your MCP client.
The Local API switch in the terminal is the stop switch. Switch it off and the agent can no longer read or trade.
A trading answer is accepted, not filled. The agent reads the outcome with
open_orders and recent_fills.
place_order and place_trigger need a client_key. A repeated call with
the same key places nothing new.
The server never sees exchange keys, and the token never appears in a message.
What is not available
The Moscow Exchange (MOEX) is not served. An agent cannot move several orders at once, move a stack between tabs or change the widths of columns.
Troubleshooting
A failed call is a tool error. Its text starts with a stable code.
| Code | Why | What to do |
|---|---|---|
terminal_unreachable | The terminal is not running or its Local API is switched off | Start the terminal and switch the Local API on |
local_api_disabled | The Local API is switched off | Switch it on in Settings App → General → Local API |
token_missing | SPECTRE_LOCAL_API_TOKEN is not set for the server | Add the token to the configuration of the server |
unauthorized | The token does not match | Copy the current token into the configuration |
incompatible_terminal | The terminal serves another API version | See Compatibility |
not_active | The clusters or the leverage of the instrument are not loaded yet | Ask again in a few seconds, or open the instrument in the terminal |
rate_limited | More than 50 instruments opened only for the API, or more than 5 new ones a second | Slow down |
The other codes are the codes of the API, see Errors.