Trading Desk
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
trading-desk
A record of your trades under the strategies that allowed them. You write each strategy down as a short Markdown file with a rules block. Every trade belongs to one strategy, at one version of it, in one run. The desk stores your decisions about each trade, with your reasons and screenshots, in an append-only SQLite log, and works out how each trade ended whenever you read it, checks each trade against its strategy's rules when you enter it, and reports performance per strategy, per version and per run.
Status: 0.9.0, the MCP server and the Claude Code plugin — on GitHub only. PyPI keeps 0.5.0 until 1.0, so install from the repository to use this version (see Install). This release stores the record, reads each trade's outcome (a replay trade's is what you report; a live trade's is worked out from price bars, with your reports overriding it), checks each trade against its strategy's rules when it is entered, reports statistics, and serves all of it to an agent over MCP (see Use it from an agent). The Python API below is what each tool calls, one to one.
Since 0.5 this is a new tool, not an upgrade of 0.4. 0.4 was a portfolio book with a terminal UI. Both are gone, along with its commands (
desk,desk-migrate,desk-check,desk-mcp), its[mcp]extra and itshub.dbformat. The desk does not read 0.4's data, and a 0.4 book is refused rather than misread.
The model
Thing | What it is |
Strategy | A Markdown file you write: the idea, how you enter, where the target and the stop go, one |
Version | A strategy's text at one moment. Any change to the text makes a new version, except for spacing within a line, trailing spaces, line endings and extra blank lines. A version never changes once saved, so it tells you exactly what each of its trades was taken under. |
Run | One version deployed over a period. Its mode is |
Trade | One entry in one run: ticker, side, a market or limit entry, stop, target, size, currency (CAD or USD), your reasons in your own words, and screenshots. |
Decision | Anything you do to a trade after entering it: move the stop or target, close it by hand, report what the order or the position did, correct a mistake, or void it. Each carries a reason. |
Two principles hold everything together:
Only decisions and bars are stored. Your reports of what an order or a position did are decisions too. Price bars are stored as they were fetched and never changed. Exits, fills, statistics and whether a trade kept its rules are worked out from those two whenever they are read. Nothing derived is stored, so nothing can go stale. (The one exception: the rule results the desk showed you when you entered a trade, and the market values and checklist answers you gave, are kept with it, as a record of what you saw.) A correction is a new entry that is read in place of the one it corrects. Nothing is ever edited or deleted.
One timing rule. An entry, a move, a close and a report each have an
at, in UTC: the moment a decision takes effect, or the moment whose state a report gives. In a live run an entry's, a move's and a close'satdefaults to now. A report always gives its own, live or replay, and none is dated after now. In a replay run you must give everyat, as the close of the bar you acted on. A decision takes effect from the first bar that opens at or after itsat. A time without a timezone is refused, never guessed. Corrections and voids are record-keeping, not market decisions: they are dated when you make them.
Related MCP server: Vibecheck
A strategy
---
name: Pullback in an uptrend
---
## Idea
Buy a shallow pullback in a stock that is already rising, with the stop under the pullback low.
## Rules
```rules
timeframes = ["1h", "15m"]
min_reward_risk = 2
max_risk_per_trade = { USD = 100, CAD = 130 }
stop_required = true
target_required = true
sides = ["long"]
max_open_trades = 2
cooldown_after_loss = { minutes = 60, same_ticker = true }
daily_loss_limit = { R = 2 }
[rsi]
timeframe = "15m"
long = { at_most = 40 }
```
## Checklist
- The pullback came on lighter volume than the move up.A template ships with the package (desk/strategy.example.md). The block is TOML. Every
value is read when the strategy is saved: an unknown rule, an unreadable value, a value in the
wrong unit, or a duplicate is refused, naming the rule and the fix. No rule is ever silently
dropped, and a block in the old line format (timeframes: 1h) is refused with the TOML form.
When you enter a trade, the desk checks it against the rules of the run's version, as of the
trade's at, and shows you each result: kept, breached, or unknown, naming what is missing.
A breach never refuses a trade, and nothing is read as kept for want of data. The results
shown are kept with the trade. get_trade also works them out again now, as checks_now,
and lists the rules whose answer has changed in checks_differ.
Rule | Meaning |
| Required. The bar sizes the strategy trades on, e.g. |
| The smallest reward-to-risk you will take: the distance from the entry to the target divided by the distance from the entry to the stop. |
| The most you will lose if the stop is hit, per currency, e.g. |
|
|
| The sides ( |
| How many trades this run may hold at once. A pending limit order counts. |
| How many trades the run may enter in a day (the system timezone's midnight to midnight). |
| How many losses in a row the run may take within the day before the next trade. |
| The most R the run may lose in a day, e.g. |
| How long to wait after a loss, |
|
|
| The stop's distance in ATRs ( |
| An indicator's value on a |
| The close above or below a moving average ( |
| Named values you supply at entry, each with a comparison, e.g. |
The checklist is the top-level bullets under ## Checklist. Each is answered at entry with
pass or fail and a reason. The answers are shown apart from the rule results and take no
part in whether a trade kept its rules.
The desk computes an indicator from price bars it fetches (a live run) or from the market
dict you give trade, which holds a number per key the rules read, such as rsi_14_15m,
macd_hist_12_26_9_15m, close_1h, ema_200_1h or a fact's own name. Your value is used in
place of the desk's, and both are kept, so the gap from your chart shows. In a replay run give
every key; in a live one, an indicator the bars cannot give reads unknown and names the key to
supply (a future's Yahoo feed is delayed, so supply its keys).
Install
uv tool install 'trading-desk @ git+https://github.com/IngTian/trading-desk'pip install 'trading-desk @ git+https://github.com/IngTian/trading-desk'The uv tool line puts trading-desk on the PATH, which the Claude Code plugin needs.
That is this version. pip install trading-desk from PyPI gives 0.5.0 until 1.0 is released.
Install it into the Python environment you will import it from: the desk is used
from Python, and it has two commands, trading-desk mcp and trading-desk integrity. Python
3.11 or later, built with SQLite 3.38 or later, on macOS or Linux. The package requires the mcp SDK and
yfinance (with pandas and numpy), which live runs read their bars through.
Use it from an agent
In Claude Code, install the plugin (it needs trading-desk on your PATH, see Install):
/plugin marketplace add IngTian/trading-desk
/plugin install trading-desk@trading-deskTo register the server by hand, or for another MCP client, run
claude mcp add trading-desk -- trading-desk mcp.
The 16 tools are save_strategy, get_strategy, list_strategies, start_run, stop_run,
list_runs, trade, move_order, close_trade, report, correct_trade, void_trade,
get_trade, list_trades, trade_bars and stats. Each is the Python function of the same
name. Replies are JSON with UTC times. A refusal comes back as a tool error that says what to
change, and a refused call writes nothing. The first start creates desk.db.
Claude Code asks before each tool call unless mcp__plugin_trading-desk_desk__* is allowed in
your settings. A pasted image is passed as a file path or a link; the desk copies the file when
the trade is recorded.
Use it from Python
from datetime import UTC, datetime
from desk import api, config, store
store.create() # once: makes desk.db under the data root
con = store.open()
text = config.example_strategy().read_text() # or your own strategy's Markdown
api.save_strategy(con, "pullback", text)
def utc(day, hour, minute=0): # a moment in the replayed history
return datetime(2026, 3, day, hour, minute, tzinfo=UTC)
run = api.start_run(con, "pullback", mode="replay", currency="USD", tags=["paper"], at=utc(2, 14))
t = api.trade(con, run.id, ticker="ACME", side="long", entry_type="limit",
entry=100.0, stop=98.5, target=103.0, size=10, currency="USD",
instrument="stock",
reasons="Held the rising trend line on the hourly; a limit at the dip's low.",
screenshots=["https://www.tradingview.com/x/AbCd1234/"], at=utc(2, 14))
api.report(con, t.id, state="filled", at=utc(2, 15, 15),
reason="The 15:00 bar traded down to it.")
t = api.report(con, t.id, state="exited", kind="target", at=utc(3, 16, 30),
reason="The target filled.")
t.outcome # status "exited", fill 100.0, exit 103.0 at its target, r 2.0, cash 30.0A live run is the same without the reports: start it with mode="live", leave out at to
mean now, and each read judges the trade from Yahoo's bars. Report only what the bars got
wrong, such as the broker's fill.
Call | Does |
| Save a strategy (a new version whenever its text changes), read one, list them. Saving over an existing strategy needs |
| Deploy a version, stop it, list runs. A run trades in one currency, |
| Enter a trade, with your reasons and screenshots. A screenshot is a local file, copied into the store under its content hash, or an |
| Move the stop or target, or close by hand: the decision to get out, which the bars price on a live run. On a replay run a position's exit is reported instead, with its price ( |
| Report the trade's state as of |
| Correct a mistake (a new entry, read in place of the one it corrects): the entry, a move ( |
| Read trades back, with their decisions folded together and their |
| A live trade's bars at one of its run's timeframes (the finest by default): from |
| Counts, rates and averages for one scope: |
A refusal raises api.Refused, whose message says what was wrong and how to fix it. A
refused call writes nothing. On a live run, move_order, close_trade and a correction of a
move's at are refused once the bars put the exit before them, since there is nothing left
to act on. If the bars ended the trade wrongly, the refusal names the report that fixes it:
open, when the broker still held the position, or exited with the broker's price.
Tracking a trade (its largest move for you or against you while it was open, the drift after
the exit, anything per strategy) is your own code: it reads get_trade and trade_bars each
time it runs, so a correction or a void shows up on its next run.
How a trade's outcome is read
Both modes share one state model. An order (how the trade enters) is pending, filled or
cancelled: a market order fills as you enter it, and a limit order (one to buy at its price
or lower, or to sell at its price or higher) is pending until it fills or is cancelled. A
position is open until it exits at its stop, at its target or by hand, at a price and a
time. Every read carries the trade's outcome: its status, the fill, the exit and its
reason, R, and cash (the price move × size × point value, in the trade's currency).
Replay runs are reported
One call, report, is the only intake. A report states the trade's state as of its at,
which every report gives:
| Says |
| The limit order filled, at the limit unless you give |
| It never will, and |
| The position was still held at |
| The position closed: |
No bars are read, and a position with no exit reported reads open.
Live runs are judged
Live runs are judged from Yahoo's 1-minute price bars, whatever the strategy's timeframes. The bars are unadjusted (not rewritten for a later
split or dividend) and regular-session (the exchange's normal hours, without pre- or
after-market trading). A future is read as Yahoo's rolling front month, e.g. GC=F for GC:
the contract nearest its expiry, so the series switches to the next contract at a roll. A
stock or an ETF in CAD is read as its Toronto listing (.TO). Reading a trade fetches the
completed bars it lacks, only while the trade has not ended, and keeps them in bars.db.
Yahoo keeps 1m bars
about 30 days, so a live trade not read for longer than that can become "not judged".
Your reports override the bars. The judge continues from your latest report:
A fill fixes the entry, for example at the broker's actual price.
opensays the position was still held then, which sets aside an exit the bars found before it. Date it at or after that exit: an exit in the same bar as the report stands, since a bar cannot say which came first, and the read says so.A cancellation or an exit ends the trade.
A live read shows outcome (your reports over the judge), judged (the bars' own reading,
which takes no fill, price or open state from your reports) and differs (the fields where
the two part). The
difference is slippage (the gap between the price the bars give and the one you got), and
worth keeping.
Every report is checked against your record before it is kept
The checks need no market data:
A fill only on a pending limit order, and never worse than the limit.
A cancellation says why:
not filledorpulled(a run stop's readsrun stopped), so the limit orders that never filled can be counted apart from the ones you pulled.An exit or an
openreport only on a position, so a limit order's fill is reported first, and anopenreport comes before the close.A stop exit is never better than the stop, and a target exit never worse than the target.
Every report is in order with the entry, the moves and the close, and none is dated after now.
A report that fails one is refused, saying which, and nothing is written.
The judge's assumptions
A fill or an exit is dated at the close of the bar it happened in.
A stop the price gapped through (a bar that opened beyond it) fills at the bar's open, and a target fills at the target price.
A bar that reaches both the stop and the target counts as the stop.
A limit order never fills better than its price, and in the bar it fills only the stop counts.
A position that opens with its stop already at or beyond its price (a stop moved past a pending limit, or a fill reported beyond the stop) is stopped out at once, at that price: no gain and no loss.
A hand close exits at the close of the last bar opening before it, or at the entry price when no bar traded between the entry and the close, unless the trade exited first. That bar counts its stop and its target when it had finished by the close, and only its stop when it was still forming.
A run stop cancels pending limit orders and closes nothing.
An entry's own bar (market or limit), and a reported fill's, is not judged.
When bars are missing, the trade reads "not judged": the missing range is named, and nothing after it is claimed.
Limits
A split or another corporate action (a merger, a special dividend) during an open live trade is not adjusted for, because Yahoo's bars are unadjusted.
A future's 1d or 1w indicator is not computed: supply it in
market.
Where your data lives
Everything lives under one folder: ~/Documents/trading-desk/ by default, or
$TRADING_DESK_HOME.
desk.db strategies, runs, trades and every decision, reports included (append-only)
bars.db price bars for live runs, and the range each fetch covered (insert-only)
attachments/ screenshots, by content hash0.9 does not read a 0.6 desk.db (or a 0.5 one): there is no migration.
$TRADING_DESK_DB moves only the database: it names one file in place of desk.db.
Screenshots and bars.db still go to the root, so to keep a session apart from your real
data, set $TRADING_DESK_HOME instead.
Both databases use a rollback journal, never WAL, because ~/Documents is often synced by
iCloud, and a database synced apart from its -wal file can be corrupted. Write from one
machine at a time.
trading-desk integrity checks the log for shapes it should never hold: a trade with no
entry, a decision dated before its trade, a move at or after the close, a report the record
does not allow, and more. It prints each one, and exits 1 if it found any, or if there is no
desk.db to check; 0 if the log is clean. It runs SQLite's quick_check on the file first,
and reports a damaged file, or a check SQLite cannot run, as a violation, never a traceback.
quick_check skips some of what integrity_check does, so for the slower, fuller check, run
sqlite3 -readonly desk.db 'PRAGMA integrity_check'.
Roadmap
Release | Adds |
0.5 | The record. |
0.6 | Reported states, bars and the judge. |
0.7 | Rule checks when you enter a trade (the results you were shown are kept with it), and statistics per run, version and strategy. |
0.8 | The MCP server and a Claude Code plugin, so an agent records your trades and decisions for you |
0.9 | Live runs judged on 1-minute bars, a trade must name its instrument, wrong-side stops and targets refused, and the agent told more (this release). |
1.0 | The release, once all of the above has landed. |
Development
uv sync
uv run pytest -q
uv run ruff check .
uv run python tools/no_real_figures.pySee CONTRIBUTING.md. MIT licensed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Trading journal with pattern detection: log trades by voice, query your own history.
AI trading partner and trading journal: trades, reports, journaling, market data.
Chart-first trading journal: log trades from notes or chart screenshots, review setups and stats.
Trading journal, options risk checks, position sizing and Monte Carlo analytics for AI assistants.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceEnables portfolio and trade journaling by tracking accounts, holdings, manual trades, open and closed positions, realized and unrealized P&L, and trade reasons through discoverable MCP tools, resources, and prompts.1-
- FlicenseAqualityBmaintenanceA passive MCP work ledger that lets coding agents record and track shared task plans, session ancestry, work claims, locations, blockers, and commits in SQLite through nine reporting tools.9-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to log trades from chart screenshots, validate them against custom strategy rules, import statements from MT5/TradingView and other brokers, and review R-based statistics in a local dashboard.79 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to self-report every tool call, token usage, decision, and session grade into a local SQLite store, so users can trace execution, audit reasoning, and see per-session costs in a local dashboard. Also supports proxy mode to intercept and trace MCP tool invocations for agents that cannot self-report.79 npm2MIT