📌Overview

Purpose: To provide a comprehensive Model Context Protocol (MCP) server for stock traders that facilitates stock analysis and enhances trading decisions.

Overview: The MCP Trader Server offers a suite of powerful tools designed to assist stock traders in performing technical analyses, comparing stocks to benchmarks, managing trading positions, and recognizing market patterns. By utilizing advanced data analysis capabilities and external market data, this server empowers traders with insights necessary for informed decision-making.

Key Features:

analyze-stock: Conducts in-depth technical analysis of stock symbols including moving averages, momentum indicators, and volume analysis to assist in evaluating stock performance.
relative-strength: Calculates and compares the relative strength of stocks against benchmarks over different timeframes, aiding in performance assessment and investment strategy formulation.
volume-profile: Provides insights on volume distribution by price, identifying significant price levels and assisting traders in understanding market sentiment and price action.
detect-patterns: Recognizes chart patterns in historical price data, delivering confidence scores and price target forecasts, which helps traders in prediction of future price movements.
position-size: Computes optimal position size based on risk parameters and account size, facilitating risk management strategies during trading.
suggest-stops: Suggests strategic stop loss levels based on technical analysis to help traders minimize losses and protect their investments.

MCP Trader Server

A Model Context Protocol (MCP) server for stock traders.

Features

Tools

The server provides the following tools for stock analysis and trading:

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
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) and performance comparison
volume-profile: Analyzes volume distribution by price
- Required argument: symbol (string, e.g. "MSFT")
- Optional argument: lookback_days (integer, default: 60)
- Returns volume profile including:
  - Point of Control (POC) - price level with highest volume
  - Value Area (70% of volume range)
  - Top volume price levels
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, dollar risk, and potential profit targets
suggest-stops: Suggests stop loss levels based on technical analysis
- Required argument: symbol (string, e.g. "META")
- Returns multiple stop loss suggestions including ATR-based stops, percentage-based stops, and technical levels

Technical Analysis Capabilities

The server leverages several specialized analysis modules:

TechnicalAnalysis: Core technical indicators and trend analysis
- Moving averages (SMA 20, 50, 200)
- Momentum indicators (RSI, MACD)
- Volatility metrics (ATR, Average Daily Range Percentage)
- Volume analysis (20-day average volume)
RelativeStrength: Comparative performance analysis
- Multi-timeframe relative strength scoring (21, 63, 126, 252 days)
- Performance comparison against benchmark indices
- Outperformance/underperformance classification
VolumeProfile: Advanced volume analysis
- Price level volume distribution
- Point of Control (POC) identification
- Value Area calculation (70% of volume)
PatternRecognition: Chart pattern detection
- Support/resistance levels
- Common chart patterns (head and shoulders, double tops/bottoms, etc.)
- Confidence scoring for detected patterns
RiskAnalysis: Position sizing and risk management
- Risk-based position sizing
- Multiple stop loss strategies
- R-multiple profit target calculation

Data Sources

The server uses the Tiingo API for market data:

Historical daily OHLCV data
Adjusted prices for accurate backtesting
Up to 1 year of historical data by default

Setup

Prerequisites

Python 3.11+
uv
ta-lib
Tiingo API Key

Environment Variables

Create a .env file:

TIINGO_API_KEY=your_api_key_here

Installing via Smithery

To install Trader for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-trader --client claude

This will:

Install the MCP Trader server
Configure it with your Tiingo API key
Set up the Claude Desktop integration

You can customize the Smithery configuration by editing smithery.yaml.

Installation

uv venv --python 3.11
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync

Docker Deployment

Build and run the Docker image:

docker build -t mcp-trader .
docker run -e TIINGO_API_KEY=your_api_key_here -p 8000:8000 mcp-trader

To 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

Configuration

Claude Desktop App

Configuration file locations:

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

Example configuration:

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

Development

Build and Run

uv build
uv run mcp-trader

HTTP Server Mode

Run the server as a standalone HTTP server:

uv run mcp-trader --http

Endpoints:

GET /list-tools: Lists available tools and schemas
POST /call-tool: Executes a tool with given arguments

Example request body:

{
  "name": "analyze-stock",
  "arguments": {
    "symbol": "AAPL"
  }
}

Debugging

Use the MCP Inspector:

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-trader run mcp-trader

Example Usage

In Claude Desktop:

Analyze the technical setup for NVDA

The server returns a technical analysis summary including trend status, momentum indicators, and key metrics.

Dependencies

Check pyproject.toml for full dependency list. Key dependencies include:

aiohttp >=3.11.11
mcp >=1.2.0
numpy ==1.26.4
pandas >=2.2.3
pandas-ta >=0.3.14b0
python-dotenv >=1.0.1
setuptools >=75.8.0
ta-lib >=0.6.0

Contributing

Contributions to MCP Trader are welcome! Ways to contribute:

Add new tools
Improve existing tools
Add data sources
Improve documentation
Bug fixes

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Future Plans

Planned enhancements include:

Portfolio Analysis
Backtesting
Sentiment Analysis
Options Analysis
Real-time Data support
Custom Strategies framework
Alerts for price and indicator levels

mcp-trader