Agent Trading Journal

Agent Trading Journal: an AI trading journal (MCP server) for Claude Code and Codex

[npm] [test] [License: MIT] [MCP] [Node]

Works with: Claude Code · Codex CLI · Claude Desktop · Cursor · Windsurf · any MCP client — Markets: forex, futures, stocks, crypto — Imports: MetaTrader 4/5, TradingView, IBKR, NinjaTrader, Tradovate and more

A trading journal your AI agent writes for you. Paste a chart screenshot into Claude Code, Codex or any MCP client. The agent reads it, fills in your strategy's fields, checks the trade against your rules, logs it, and attaches the image. A local dashboard shows what's working.

No forms, no LLM API key, no account. Everything stays on your machine in one SQLite file.

[Dashboard with synthetic demo data] _{Dashboard with generated demo data (npx agent-trading-journal demo). Not a real account.}

Why this exists

Most "AI trading journals" are a web form plus a chatbot that reads your numbers afterwards. Two problems follow:

1. Logging is the bottleneck. People stop journaling because entering trades by hand is tedious.
2. Generic fields measure nothing specific. "Setup: A/B/C" doesn't tell you whether your rules work.

Here the agent is the data-entry clerk, and the journal is shaped by an onboarding interview about how you trade:

Quick start

1. Connect it to your agent. Requires Node.js 22+.

Claude Code:

claude mcp add journal -- npx -y agent-trading-journal

Codex CLI (~/.codex/config.toml):

[mcp_servers.journal]command = "npx"args = ["-y", "agent-trading-journal"]

Claude Desktop, Cursor, or any other MCP client: add a stdio server with command npx and args ["-y", "agent-trading-journal"]. Run npx agent-trading-journal setup to print all the snippets.

2. Tell your agent: "Set up my trading journal."

It interviews you in your language: markets, risk rules, how you find bias, setups, entries, stops and targets, and when you don't trade. From your answers it proposes fields (what to measure on every trade) and rules (your entry checklist). You confirm, and it saves them. See docs/ONBOARDING.md for the full script.

3. Trade or backtest as usual. Paste screenshots and say "log this". Ask for "weekly review" or "pre-session check". Say "open the dashboard" to see it at http://localhost:3777.

Just looking? npx agent-trading-journal demo fills a separate demo journal and opens the dashboard.

What the agent can do (MCP tools)

MCP prompts (slash commands in clients that support them): onboarding, log_trade_from_screenshot, weekly_review, pre_session_check. The same workflows are available through the get_workflow tool for clients without prompt support.

Concepts

• Strategy: your plan (bias, setup, entry, stop, targets, management, no-trade conditions), plus:
  • Fields: per-trade variables you want to analyse (enum, bool, number, text). Every non-text field gets its own breakdown chart.
  • Rules: your checklist, each must or should. Rule adherence compares expectancy when all must-rules were followed against when at least one was broken.
  • Versions: when fields or rules change, the version bumps. Old trades keep the version they were logged under, and removed fields are archived, not deleted.
• Session: a backtest, forward-test or live block on one symbol, optionally tied to an account.
• R: result in multiples of planned risk. Stats are R-based, so they compare across instruments and account sizes.
• Presets: presets/ has a starter template (for traders without a written strategy), a trend pullback and an opening-range breakout. They're starting points to edit, not recommendations.
• Edge Score: an open 0–100 composite (docs/edge-score.md), withheld under 5 trades.

Data and configuration

Back up by copying the data dir. run_sql_readonly and the SQLite file are yours to query.

CLI

agent-trading-journal [mcp]            MCP server on stdio (what MCP clients run)agent-trading-journal dashboard        dashboard at http://localhost:3777agent-trading-journal demo             demo data in a separate dir + dashboardagent-trading-journal import <file> --account <name> [--strategy <slug>] [--dry-run]agent-trading-journal setup            config snippets for Claude Code / Claude Desktop / Codex

Safety

This is a journaling and analysis tool. It does not place trades, connect to brokers for execution, or give financial advice. Leveraged trading is high-risk. The agent's chart reading can be wrong: every logged value is visible and editable, and rule checks show which ones failed and why.

FAQ

Do I need an OpenAI or Anthropic API key?

No. The journal is an MCP server; the AI is the agent you already use (Claude Code, Codex, Claude Desktop, Cursor…). The journal itself never calls an LLM.

Where is my data stored? Is anything sent online?

Everything is in one local SQLite file plus a screenshots folder (~/.agent-trading-journal by default). The dashboard binds to 127.0.0.1. Nothing is uploaded anywhere by the journal.

Can I use my own trading strategy?

That's the point. The onboarding interview turns your plan into custom fields and a rule checklist. Presets are only starting points. SMC/ICT, price action, supply & demand, indicators, options: anything you can describe works.

Can I import trades from MetaTrader 5 or TradingView?

Yes: import_statement (or agent-trading-journal import <file> --account <name>) reads MT4/MT5 statements, TradingView paper/strategy exports, IBKR, ThinkorSwim, NinjaTrader, Tradovate, TopstepX, Webull, DAS, TradeZella and Tradervue exports. Your agent can then add screenshots and rule checks to the imported trades.

Does it work for backtesting (TradingView Replay) and prop firm challenges?

Yes. Sessions are backtest, forward or live. Accounts can carry prop-firm limits (daily loss, max drawdown, trades per day, loss streak), and check_risk warns before you hit them.

Does it place trades or give signals?

No. It only records and analyses. You make every trading decision.

Credits and license

MIT © 2026 smizxe.

Statement parsing and round-trip reconstruction use @luxalgo/journal-importers and @luxalgo/journal-core (MIT) from LuxAlgo's Trade Journal. The Edge Score is adapted from their open formula. This project is not affiliated with or endorsed by LuxAlgo.