README.md•7.41 kB
# Stock Data MCP Server
A Model Context Protocol (MCP) server that provides real-time stock market data through Yahoo Finance **without requiring an API key**. Get quotes, historical data, company information, financial statements, and more.
## Features
- 🔍 **Real-time Stock Quotes** - Current prices, changes, volume, and market data
- 📊 **Historical Data** - OHLCV data with customizable periods and intervals
- 🏢 **Company Information** - Detailed company profiles, sectors, and metrics
- 💰 **Financial Statements** - Income statements, balance sheets, and cash flow
- 🔎 **Ticker Search** - Find ticker symbols by company name
- 🆓 **No API Key Required** - Uses public Yahoo Finance data via yfinance
- 🚀 **Railway Ready** - Deploy to Railway.app with one click
## Available Tools
### 1. `get_stock_quote`
Get current stock price and trading data.
**Parameters:**
- `symbol` (string, required): Stock ticker symbol (e.g., "AAPL", "MSFT")
- `response_format` (string, optional): "markdown" or "json" (default: "markdown")
**Example:**
```json
{
"symbol": "AAPL",
"response_format": "markdown"
}
```
### 2. `get_stock_info`
Get comprehensive company information and metrics.
**Parameters:**
- `symbol` (string, required): Stock ticker symbol
- `response_format` (string, optional): "markdown" or "json"
**Example:**
```json
{
"symbol": "TSLA",
"response_format": "json"
}
```
### 3. `get_stock_history`
Get historical price and volume data.
**Parameters:**
- `symbol` (string, required): Stock ticker symbol
- `period` (string, optional): "1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd", "max" (default: "1mo")
- `interval` (string, optional): "1m", "5m", "1h", "1d", "1wk", "1mo", etc. (default: "1d")
- `response_format` (string, optional): "markdown" or "json"
**Example:**
```json
{
"symbol": "NVDA",
"period": "6mo",
"interval": "1d",
"response_format": "json"
}
```
### 4. `get_stock_financials`
Get company financial statements.
**Parameters:**
- `symbol` (string, required): Stock ticker symbol
- `statement_type` (string, optional): "income", "balance", "cashflow" (default: "income")
- `quarterly` (boolean, optional): true for quarterly, false for annual (default: false)
- `response_format` (string, optional): "markdown" or "json"
**Example:**
```json
{
"symbol": "GOOGL",
"statement_type": "income",
"quarterly": false,
"response_format": "markdown"
}
```
### 5. `search_ticker`
Search for ticker symbols by company name.
**Parameters:**
- `query` (string, required): Company name or partial name
- `response_format` (string, optional): "markdown" or "json"
**Example:**
```json
{
"query": "Apple",
"response_format": "json"
}
```
## Local Development
### Prerequisites
- Python 3.11 or higher
- pip
### Installation
1. Clone this repository:
```bash
git clone <your-repo-url>
cd stock-mcp-server
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Run the server locally (stdio mode):
```bash
python stock_mcp.py --transport stdio
```
### Testing with MCP Inspector
```bash
npx @modelcontextprotocol/inspector python stock_mcp.py
```
This opens a web interface where you can test all the tools interactively.
## Railway Deployment
### Quick Deploy
1. **Push to GitHub:**
```bash
git init
git add .
git commit -m "Initial commit"
git remote add origin <your-github-repo>
git push -u origin main
```
2. **Deploy to Railway:**
- Go to [railway.app](https://railway.app)
- Click "New Project" → "Deploy from GitHub repo"
- Select your repository
- Railway will automatically detect the Dockerfile and deploy
3. **Get Your Server URL:**
- Once deployed, Railway provides a public URL like: `https://your-app.railway.app`
- Copy this URL for Claude Desktop configuration
### Environment Variables
**No environment variables required!** This server doesn't need API keys because it uses public Yahoo Finance data.
Railway automatically sets the `PORT` variable - don't override it.
## Claude Desktop Integration
After deploying to Railway, add this to your Claude Desktop config:
**Config location:**
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
**Configuration:**
```json
{
"mcpServers": {
"stock-data": {
"url": "https://your-app.railway.app",
"transport": "streamable-http"
}
}
}
```
Replace `your-app.railway.app` with your actual Railway URL.
**Restart Claude Desktop** after saving the configuration.
## Docker Usage
### Build the Image
```bash
docker build -t stock-mcp-server .
```
### Run Locally
```bash
docker run -p 8080:8080 -e PORT=8080 stock-mcp-server
```
### Test the Server
```bash
# Health check
curl http://localhost:8080
# List available tools
curl -X POST http://localhost:8080/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'
```
## Usage Examples
### Get Apple Stock Quote
**Request to Claude:**
> "What's the current price of Apple stock?"
**Behind the scenes:**
Claude calls `get_stock_quote` with `{"symbol": "AAPL"}`
### Analyze Tesla Financials
**Request to Claude:**
> "Show me Tesla's latest income statement"
**Behind the scenes:**
Claude calls `get_stock_financials` with `{"symbol": "TSLA", "statement_type": "income"}`
### Compare Historical Performance
**Request to Claude:**
> "Compare the 6-month performance of NVIDIA and AMD"
**Behind the scenes:**
Claude calls `get_stock_history` multiple times and analyzes the data
## Troubleshooting
### "Unable to fetch data for symbol"
- Verify the ticker symbol is correct
- Use `search_ticker` to find the right symbol
- Some international stocks may not be available
### Railway Deployment Issues
- Check Railway logs in the dashboard
- Verify the Dockerfile builds successfully locally
- Ensure you're not setting the PORT environment variable manually
### Claude Desktop Connection Issues
1. Verify the URL has no trailing slash
2. Confirm `transport` is set to `"streamable-http"`
3. Check Claude Desktop logs (Help → View Logs)
4. Restart Claude Desktop after config changes
## Data Source
This server uses [yfinance](https://github.com/ranaroussi/yfinance), an open-source library that retrieves data from Yahoo Finance. The data is provided for informational purposes only and should not be used for trading decisions without verification.
**Data Limitations:**
- Real-time data may have a 15-20 minute delay
- Some international stocks may have limited data
- Historical data availability varies by symbol
- Financial statements may not be available for all companies
## Architecture
**Transport:** SSE (Server-Sent Events) for Railway, stdio for local development
**Framework:** FastMCP (MCP Python SDK)
**Data Validation:** Pydantic v2
**Stock Data:** yfinance (Yahoo Finance API wrapper)
## License
MIT License - See LICENSE file for details
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
## Support
For issues or questions:
- Open an issue on GitHub
- Check the [MCP documentation](https://modelcontextprotocol.io)
- Review Railway's [deployment guides](https://docs.railway.app)