MCP Trader Server

A simplified Model Context Protocol (MCP) server for stock and cryptocurrency analysis. This version is optimized for learning with minimal configuration and clear code structure.

Features

Technical Analysis Tools

The server provides the following tools for market analysis:

analyze-stock: Performs technical analysis on a given stock symbol
- Required argument: symbol (string, e.g. "NVDA")
- Returns comprehensive technical analysis including:
  - Moving average trends (20, 50, 200 SMA)
  - Momentum indicators (RSI, MACD)
  - Volatility metrics (ATR, ADRP)
  - Volume analysis
analyze-crypto: Performs technical analysis on cryptocurrency assets
- Required argument: symbol (string, e.g. "BTC", "ETH", "BTCUSDT" for Binance)
- Optional arguments:
  - provider (string, default: "tiingo", options: "tiingo", "binance")
  - lookback_days (integer, default: 365)
  - quote_currency (string, default: "usd" for Tiingo, "USDT" for Binance)
- Returns comprehensive technical analysis including all stock indicators plus crypto-specific metrics
relative-strength: Calculates a stock's relative strength compared to a benchmark
- Required argument: symbol (string, e.g. "AAPL")
- Optional argument: benchmark (string, default: "SPY")
- Returns relative strength metrics across multiple timeframes (21, 63, 126, 252 days)
volume-profile: Analyzes volume distribution by price
- Required argument: symbol (string, e.g. "MSFT")
- Optional argument: lookback_days (integer, default: 60)
- Returns volume profile analysis including Point of Control (POC) and Value Area
detect-patterns: Identifies chart patterns in price data
- Required argument: symbol (string, e.g. "AMZN")
- Returns detected chart patterns with confidence levels and price targets
position-size: Calculates optimal position size based on risk parameters
- Required arguments:
  - symbol (string, e.g. "TSLA")
  - stop_price (number)
  - risk_amount (number)
  - account_size (number)
- Optional argument: price (number, default: current price)
- Returns recommended position size and R-multiple profit targets
suggest-stops: Suggests stop loss levels based on technical analysis
- Required argument: symbol (string, e.g. "META")
- Returns multiple stop loss suggestions based on ATR, percentages, and technical levels

FastMCP Resources (NEW)

The server now supports FastMCP resources for direct market data access:

Stock Resources

stock://{symbol} - Get current stock price and statistics
stock://{symbol}/history - Get historical price data

Crypto Resources

crypto://{symbol} - Get current crypto price (supports Tiingo & Binance)
crypto://{symbol}/history - Get historical crypto data

Cache Resources

market://cache/clear - Clear the data cache
market://cache/status - View cache statistics

Data Sources

Stocks: Tiingo API for historical daily OHLCV data
Crypto:
- Tiingo API for major pairs (BTC, ETH, etc. paired with USD)
- Binance API for extended pairs and USDT quotes

Setup

Prerequisites

Python 3.11+
uv package manager
Tiingo API Key
Optional: ta-lib for enhanced performance (see INSTALL.md)

Environment Variables

Create a .env file in your project root:

# MCP Trader
# Copy this file to .env for API access

# Tiingo API Key (free tier works great)
# Get yours at: https://www.tiingo.com/
TIINGO_API_KEY=your_tiingo_api_key_here

# Optional: For higher rate limits
BINANCE_API_KEY=your_binance_api_key_here
BINANCE_API_SECRET=your_binance_api_secret_here

Installation

# Clone the repository
git clone https://github.com/wshobson/mcp-trader.git
cd mcp-trader

# Create virtual environment and install dependencies
uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

# Copy the example environment file
cp .env.example .env
# Edit .env and add your Tiingo API key

Configuration

Claude Desktop App

The configuration file location varies by platform:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Standard MCP Configuration

{
  "mcpServers": {
    "stock-analyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-trader",
        "run",
        "mcp-trader"
      ],
      "env": {
        "TIINGO_API_KEY": "your_api_key_here"
      }
    }
  }
}

FastMCP Configuration (with Resources)

To enable FastMCP resources alongside the standard tools:

{
  "mcpServers": {
    "stock-analyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-trader",
        "run",
        "python",
        "-m",
        "mcp_trader.fastmcp_server"
      ],
      "env": {
        "TIINGO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Running Tests

The project includes a comprehensive test suite with 80% code coverage:

# Run all tests
pytest

# Run with coverage report
pytest --cov=src/mcp_trader --cov-report=term-missing

# Run specific test file
pytest src/mcp_trader/tests/test_indicators.py

# Run with verbose output
pytest -v

Running the Server

Standard Mode

Runs the MCP server with all tools:

uv run mcp-trader

Development Mode

For development and debugging:

# Run with Python directly
uv run python -m mcp_trader.server

# Run with MCP Inspector for debugging
npx @modelcontextprotocol/inspector uv --directory . run mcp-trader

Docker Deployment

# Build the Docker image
docker build -t mcp-trader .

# Run the container
docker run -e TIINGO_API_KEY=your_api_key_here -p 8000:8000 mcp-trader

# Run in HTTP server mode
docker run -e TIINGO_API_KEY=your_api_key_here -p 8000:8000 mcp-trader uv run mcp-trader --http

Example Usage

In Claude Desktop, simply ask:

Analyze the technical setup for NVDA

The server will return a comprehensive technical analysis including trend status, momentum indicators, and key metrics.

For crypto analysis:

Analyze BTC using Binance data

Project Structure

mcp-trader/
├── src/mcp_trader/
│   ├── __init__.py       # Package initialization
│   ├── server.py         # Main MCP server (simplified)
│   ├── config.py         # Simple configuration dataclass
│   ├── models.py         # Pydantic models for type safety
│   ├── data.py           # Market data providers
│   ├── indicators.py     # Technical analysis calculations
│   └── tests/            # Comprehensive test suite
├── .env.example          # Example environment configuration
├── pyproject.toml        # Project dependencies
└── README.md             # This file

Troubleshooting

Common Issues

"TIINGO_API_KEY not set" error
- Copy .env.example to .env
- Add your Tiingo API key to the .env file
Test failures
- Ensure all dependencies are installed: uv sync
- Run tests with verbose output: pytest -v
Import errors
- Make sure you're in the virtual environment: source .venv/bin/activate
- Reinstall dependencies: uv sync --force-reinstall

Dependencies

Core dependencies:

aiohttp >=3.11.11
fastmcp >=0.4.2
numpy >=1.26.4,<2.0
pandas >=2.2.3
pandas-ta >=0.3.14b0
python-dotenv >=1.0.1
setuptools >=75.8.0

Optional:

ta-lib >=0.6.0 (for enhanced performance)

See pyproject.toml for the complete list.

Learning Resources

Understanding the Code

Start with server.py: The main entry point showing how MCP tools are defined
Study models.py: Learn about type-safe request/response handling with Pydantic
Explore indicators.py: See how technical analysis calculations are implemented
Review tests: The test suite demonstrates proper usage of each component

Key Concepts

MCP Tools: Functions exposed to AI assistants via the Model Context Protocol
Technical Indicators: Mathematical calculations on price/volume data
Type Safety: Using Pydantic models for validation and documentation
Async Programming: All tools use async/await for concurrent operations

Contributing

Contributions that improve clarity and learning are especially welcome:

Fork the repository
Create a feature branch
Write clear, well-tested code
Ensure tests pass with good coverage
Submit a pull request

Contributors

Future Plans

Portfolio Analysis: Tools for analyzing and optimizing portfolios
Backtesting: Test trading strategies on historical data
Sentiment Analysis: Integration with news and social media data
Options Analysis: Tools for options strategies and pricing
Real-time Data: Support for real-time market feeds
Custom Strategies: Framework for custom trading strategies
Alerts: Price and technical indicator notifications

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.github		.github
src/mcp_trader		src/mcp_trader
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
Dockerfile		Dockerfile
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
smithery.yaml		smithery.yaml
technical-mcp.png		technical-mcp.png
uv.lock		uv.lock

License

wshobson/mcp-trader

Folders and files

Latest commit

History

Repository files navigation

MCP Trader Server

Features

Technical Analysis Tools

FastMCP Resources (NEW)

Stock Resources

Crypto Resources

Cache Resources

Data Sources

Setup

Prerequisites

Environment Variables

Installation

Configuration

Claude Desktop App

Standard MCP Configuration

FastMCP Configuration (with Resources)

Running Tests

Running the Server

Standard Mode

Development Mode

Docker Deployment

Example Usage

Project Structure

Troubleshooting

Common Issues

Dependencies

Learning Resources

Understanding the Code

Key Concepts

Contributing

Contributors

Future Plans

Further Reading

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 5

Uh oh!

Languages

Packages