mcp-trader

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 )

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

1. "TIINGO_API_KEY not set" error

   • Copy .env.example to .env
   • Add your Tiingo API key to the .env file

2. Test failures

   • Ensure all dependencies are installed: uv sync
   • Run tests with verbose output: pytest -v

3. 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 for the complete list.

Learning Resources

Understanding the Code

1. Start with server.py: The main entry point showing how MCP tools are defined
2. Study models.py: Learn about type-safe request/response handling with Pydantic
3. Explore indicators.py: See how technical analysis calculations are implemented
4. 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:

1. Fork the repository
2. Create a feature branch
3. Write clear, well-tested code
4. Ensure tests pass with good coverage
5. Submit a pull request

Contributors

• @wshobson
• @zd87pl
• @calclavia

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

Further Reading

Learn more about this project:

• Building a Stock Analysis Server with MCP, Part 1 - Initial setup and core features
• Building a Stock Analysis Server with MCP, Part 2 - Advanced analysis tools

License

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