mcp-trader

# MCP Trader Server [](https://smithery.ai/server/mcp-trader) 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](https://api.tiingo.com/) 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](https://github.com/astral-sh/uv) package manager - [Tiingo API Key](https://api.tiingo.com/) - Optional: [ta-lib](https://ta-lib.org/install/) for enhanced performance (see [INSTALL.md](INSTALL.md)) ### Environment Variables Create a `.env` file in your project root: ```bash # 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 ```bash # 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 ```json { "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: ```json { "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: ```bash # 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: ```bash uv run mcp-trader ``` ### Development Mode For development and debugging: ```bash # 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 ```bash # 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 [pyproject.toml](pyproject.toml) 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](https://github.com/wshobson) - [@zd87pl](https://github.com/zd87pl) - [@calclavia](https://github.com/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](https://sethhobson.com/2025/01/building-a-stock-analysis-server-with-mcp-part-1/) - Initial setup and core features - [Building a Stock Analysis Server with MCP, Part 2](https://sethhobson.com/2025/03/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.