finance-mcp-server

A zero-config finance MCP server for Claude Code -- real-time market data, technical analysis, and paper trading.

What is this?

finance-mcp-server is a Model Context Protocol server that gives Claude Code direct access to financial markets. It exposes 10 tools across three categories -- market data, analysis, and paper trading -- so you can ask Claude about stocks, run technical analysis, and manage a simulated portfolio, all from your terminal.

• Zero config -- works out of the box with yfinance. No API keys required.
• Paper trading -- practice trading with a virtual $100,000 portfolio that persists between sessions.
• Technical analysis -- SMA, EMA, RSI, MACD, Bollinger Bands, and structured bull/bear analysis.
• Crypto support -- track cryptocurrency prices alongside equities.

Quick Start

1. Install the package:

pip install git+https://github.com/realtonkaa/finance-mcp-server.git

2. Register with Claude Code:

claude mcp add finance -- python -m finance_mcp

3. Start using it:

> What's the current price of NVDA?
> Analyze AAPL with technicals
> Buy 10 shares of MSFT in my paper portfolio

That's it. No API keys, no config files, no environment variables.

Tools

Market Data (4 tools)

| Tool | Description | |------|-------------| | get_stock_price | Current price, daily change, volume, and 52-week range | | get_stock_history | Historical OHLCV data with configurable period (1mo -- 5y) | | get_company_info | Fundamentals -- sector, market cap, P/E, dividend yield, beta | | get_crypto_price | Cryptocurrency price with 24h change and market cap |

Example prompts:

"Get me the stock price for TSLA"
"Show 6 months of price history for SPY"
"What sector is GOOGL in and what's its P/E ratio?"
"How is Bitcoin doing today?"

Analysis (3 tools)

| Tool | Description | |------|-------------| | analyze_stock | Structured analysis with bull/bear case, technicals, and risk score (1-10) | | get_technicals | SMA(20/50), EMA(12/26), RSI(14), MACD, Bollinger Bands with signals | | compare_stocks | Side-by-side comparison of two stocks on fundamentals and technicals |

Example prompts:

"Give me a full analysis of NVDA"
"What are the technical indicators for QQQ?"
"Compare AAPL vs MSFT"

Paper Trading (3 tools)

| Tool | Description | |------|-------------| | paper_trade | Buy or sell shares at current market price | | get_portfolio | View holdings, P&L per position, and total portfolio value | | get_trade_history | Full trade log with buy/sell breakdown |

Example prompts:

"Buy 50 shares of AAPL"
"Sell 10 shares of TSLA"
"Show my portfolio"
"Show my trade history"

Paper Trading

The paper trading system gives you a virtual $100,000 cash balance to practice with. All trades execute at the current market price via yfinance.

• Persistent -- your portfolio and trade history are saved to disk between sessions.
• Realistic constraints -- you cannot spend more cash than you have or sell shares you don't own.
• Average cost tracking -- multiple buys of the same stock are tracked at weighted average cost.
• Live P&L -- portfolio view fetches current prices to show real-time profit/loss per position.

Zero Config

By default, all market data comes from yfinance, which requires no API key and covers:

• US and international equities
• Cryptocurrencies (BTC, ETH, SOL, etc.)
• ETFs and index funds (SPY, QQQ, etc.)
• Company fundamentals and historical data

Optional: Alpha Vantage

If you need higher rate limits or additional data, you can set an Alpha Vantage API key:

export ALPHA_VANTAGE_API_KEY=your_key_here

This is entirely optional. The server works fully without it.

Architecture

finance-mcp-server
|
|-- src/finance_mcp/
|   |-- server.py              # MCP server entry point (10 tools)
|   |-- __main__.py            # python -m finance_mcp
|   |
|   |-- data/
|   |   |-- provider.py        # Abstract data provider interface
|   |   |-- yfinance_provider.py  # yfinance implementation
|   |   +-- cache.py           # Request caching layer
|   |
|   |-- analysis/
|   |   |-- indicators.py      # SMA, EMA, RSI, MACD, Bollinger
|   |   +-- analyst.py         # Structured analysis & comparison
|   |
|   +-- trading/
|       |-- portfolio.py       # Portfolio manager (buy/sell/summary)
|       +-- storage.py         # JSON persistence for trades
|
+-- pyproject.toml

Data flow:

Claude Code  -->  MCP Protocol  -->  server.py  -->  yfinance_provider
                                        |
                                        +--> indicators.py (technicals)
                                        +--> analyst.py    (analysis)
                                        +--> portfolio.py  (paper trading)

Development

git clone https://github.com/realtonkaa/finance-mcp-server.git
cd finance-mcp-server
pip install -e .

Run the server directly:

python -m finance_mcp

License

MIT -- see LICENSE.

Disclaimer

This software is for educational and informational purposes only. It is not financial advice, investment advice, or trading advice. The paper trading feature uses simulated money and does not execute real trades. Always consult a qualified financial advisor before making investment decisions. The authors assume no liability for any financial losses incurred through the use of this software or the information it provides.