TradingAssistantMCP

A learning project: an MCP (Model Context Protocol) server that lets an agent (e.g. Claude) fetch stock data and, eventually, run backtests and custom trading strategies.

Setup

Requires Python 3.11+. No API keys needed yet (current tools use yfinance, which needs no signup).

python3 -m venv .venv
.venv/bin/pip install -e .

That creates an isolated environment in .venv/ and installs this project's dependencies into it. .venv/ is gitignored — anyone cloning this repo needs to run these two commands themselves before anything will work.

Running the server

The server (src/trading_assistant_mcp/server.py) isn't meant to be run directly by you — it's meant to be spawned by an MCP client (an agent) over stdio. Two ways to exercise it:

1. MCP Inspector (manual testing, no agent needed) — a browser UI for calling tools directly:

.venv/bin/mcp dev src/trading_assistant_mcp/server.py

Opens a local URL (e.g. http://127.0.0.1:6274). Click Connect, go to the Tools tab, and call a tool manually.

Requires uv to be installed (mcp dev launches the server via uv run internally, regardless of the venv above).

2. Claude Code (real agent) — registered as a project-scoped MCP server in .mcp.json. Open a Claude Code session in this directory and just ask a question like "what's the price of AAPL?" — Claude decides on its own whether to call the tool.

Portability note: .mcp.json hardcodes an absolute path to this machine's .venv/bin/python. If you clone this repo elsewhere, re-run:

claude mcp add -s project trading-assistant -- /absolute/path/to/.venv/bin/python /absolute/path/to/src/trading_assistant_mcp/server.py

What's here so far

Tools:

• get_quote(symbol) — current price, day range, volume for a stock ticker.

• get_fundamentals(symbol) — valuation/financial ratios (P/E, market cap, EPS, dividend yield, beta, 52-week range, margins, growth).

• get_candles(symbol, period, interval) — historical OHLCV bars. Note: returns can be large (hundreds of candles) — not meant to be chained into another tool call by an agent, just for direct inspection.

• get_technical_indicators(symbol, period, interval) — SMA-20/50, RSI-14, MACD, Bollinger Bands, ATR-14, volume vs. its average. Fetches its own candle data internally rather than taking get_candles's output as input, since that output is too large to round-trip through a tool call/agent context.

Prompts:

• analyze_stock(symbol) — standardized workflow: call all three data tools above, then apply a fixed textbook-interpretation rubric (trend/momentum/volatility/valuation). Explicitly framed as "what conventional signals say," not a price prediction — short-term price movement is close to a random walk and technical analysis doesn't reliably forecast it.

Project layout

src/trading_assistant_mcp/
├── server.py              # MCP server: wraps data/analysis functions as tools + the analyze_stock prompt
├── models.py               # shared types (Candle) used across data/ and analysis/
├── data/
│   └── yfinance_client.py # plain Python, no MCP dependency — reusable/testable on its own
└── analysis/
    └── indicators.py      # technical indicators computed from candle data, hand-rolled pandas (no pandas-ta)

server.py is intentionally a thin adapter: it's the only file that imports mcp. Data-fetching and (later) analysis logic stay in plain Python modules so they're testable and reusable independent of the protocol layer.

Roadmap

Current-data analysis (candlesticks, fundamentals/ratios, technical indicators) before backtesting and custom natural-language strategies (e.g. "buy AMD every time it drops 1%, sell every time it rises 5%"). See project decisions for the full plan.