agent-trading-journal

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

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 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:

• Logging is the bottleneck. People stop journaling because entering trades by hand is tedious.
• 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:

	Typical AI journal	Agent Trading Journal
Who enters trades	You, in a form	Your agent, from screenshots (or a broker statement)
How AI connects	The app calls an LLM with your API key	MCP: your agent (Claude Code / Codex / …) is the AI
What is measured	Fixed fields + free tags	Fields and a rule checklist defined for your strategy
Rules	Notes	Each rule is pass/fail per trade → "E[R] when followed vs broken"
Skipped setups	Not tracked	Logged and reviewed (was staying out right?)
Risk limits	Rarely	Prop-firm style guard: daily loss, max drawdown, trades/day, loss streak

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)

Area	Tools
Setup	get_setup_status, get_onboarding_guide, set_profile, list_presets, import_preset, upsert_strategy, get_strategy, list_strategies, export_strategy
Accounts & risk	upsert_account, list_accounts, check_risk
Journal	start_session, list_sessions, log_trade, update_trade, delete_trade, query_trades, get_trade, add_screenshot
Lessons	add_lesson, update_lesson, delete_lesson, list_lessons
Analysis	get_stats, run_sql_readonly, export_review (Markdown, Obsidian-friendly)
Import	import_statement: MetaTrader 4/5, TradingView, IBKR, ThinkorSwim, NinjaTrader, Tradovate, TopstepX, Webull, DAS, TradeZella, Tradervue, generic CSV
Dashboard	start_dashboard, stop_dashboard, dashboard_status

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

Env var	Default	Purpose
JOURNAL_DATA_DIR	~/.agent-trading-journal	folder with journal.db + screenshots/
JOURNAL_DB, JOURNAL_SCREENSHOTS	inside the data dir	override either path
JOURNAL_PORT	3777	dashboard port (binds to 127.0.0.1 only)
JOURNAL_WEB	unset	1 = start the dashboard together with the MCP server
JOURNAL_LOCALES_DIR	<data dir>/locales	extra dashboard languages as <code>.json (docs/locales.md)

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:3777
agent-trading-journal demo             demo data in a separate dir + dashboard
agent-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.