MCP Trader Server
by wshobson
# MCP Trader Server
[](https://smithery.ai/server/mcp-trader)
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)
- Includes performance comparison between the stock and benchmark
- **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) - 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 based on:
- ATR-based stops (1x, 2x, 3x ATR)
- Percentage-based stops (2%, 5%, 8%)
- Technical levels (moving averages, recent swing lows)
### 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](https://api.tiingo.com/) 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](https://github.com/astral-sh/uv)
- [ta-lib](https://ta-lib.org/install/)
- [Tiingo API Key](https://api.tiingo.com/)
### Environment Variables
Create a `.env` file:
```bash
TIINGO_API_KEY=your_api_key_here
```
### Installing via Smithery
To install Trader for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-trader):
```bash
npx -y @smithery/cli install mcp-trader --client claude
```
This will:
1. Install the MCP Trader server
2. Configure it with your Tiingo API key
3. Set up the Claude Desktop integration
#### Smithery Configuration
The server includes a `smithery.yaml` configuration file that defines:
- Required configuration parameters (Tiingo API key)
- Command function to start the MCP server
- Integration with Claude Desktop
You can customize the Smithery configuration by editing the `smithery.yaml` file.
### Installation
```bash
uv venv --python 3.11
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv sync
```
### Docker Deployment
The project includes a Dockerfile for containerized deployment:
```bash
# Build the Docker image
docker build -t mcp-trader .
# Run the container with your API key
docker run -e TIINGO_API_KEY=your_api_key_here -p 8000:8000 mcp-trader
```
To run the container in HTTP server mode:
```bash
docker run -e TIINGO_API_KEY=your_api_key_here -p 8000:8000 mcp-trader uv run mcp-trader --http
```
## Configuration
### Claude Desktop App
On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
Development 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"
}
}
}
}
```
## Development
### Build and Run
```bash
uv build
uv run mcp-trader
```
### HTTP Server Mode
The server can also run as a standalone HTTP server for testing or integration with other applications:
```bash
uv run mcp-trader --http
```
This starts an HTTP server on http://localhost:8000 with the following endpoints:
- **GET /list-tools**: Returns a list of available tools and their schemas
- **POST /call-tool**: Executes a tool with the provided arguments
- Request body format:
```json
{
"name": "analyze-stock",
"arguments": {
"symbol": "AAPL"
}
}
```
- Returns an array of content items (text, images, etc.)
### Debugging
Use the MCP Inspector for debugging:
```bash
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 will return a technical analysis summary including trend status, momentum indicators, and key metrics.
## Dependencies
See pyproject.toml for full dependency list:
```
- 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! Here are some ways you can contribute:
- **Add new tools**: Implement additional technical analysis tools or trading strategies
- **Improve existing tools**: Enhance the accuracy or performance of current tools
- **Add data sources**: Integrate additional market data providers
- **Documentation**: Improve the documentation or add examples
- **Bug fixes**: Fix issues or improve error handling
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Future Plans
The MCP Trader project has several planned enhancements:
- **Portfolio Analysis**: Tools for analyzing and optimizing portfolios
- **Backtesting**: Capabilities to test trading strategies on historical data
- **Sentiment Analysis**: Integration with news and social media sentiment data
- **Options Analysis**: Tools for analyzing options strategies and pricing
- **Real-time Data**: Support for real-time market data feeds
- **Custom Strategies**: Framework for implementing and testing custom trading strategies
- **Alerts**: Notification system for price and technical indicator alerts
## Further Reading
Learn more about this project through these detailed blog posts:
- [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, architecture, and core technical analysis features
- [Building a Stock Analysis Server with MCP, Part 2](https://sethhobson.com/2025/03/building-a-stock-analysis-server-with-mcp-part-2/) - Relative Strength, Volume, Pattern Recognition, Risk analysis