Metadata-Version: 2.4
Name: finance-mcp-server
Version: 1.0.2
Summary: MCP Server for Financial Data and Technical Indicators
Home-page: https://github.com/akshatbindal/finance-mcp-server
Author: Akshat Bindal
Author-email: Akshat Bindal <akshatbindal01@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/akshatbindal/finance-mcp-server
Project-URL: Repository, https://github.com/akshatbindal/finance-mcp-server
Project-URL: Issues, https://github.com/akshatbindal/finance-mcp-server/issues
Keywords: mcp,finance,stocks,technical-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp
Requires-Dist: yfinance
Requires-Dist: pandas
Requires-Dist: ta
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 📈 Finance MCP Server

[![PyPI version](https://badge.fury.io/py/finance-mcp-server.svg)](https://badge.fury.io/py/finance-mcp-server)
[![Python Support](https://img.shields.io/pypi/pyversions/finance-mcp-server.svg)](https://pypi.org/project/finance-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A powerful Model Context Protocol (MCP) server that brings comprehensive stock market data and technical analysis capabilities to Claude Desktop and other MCP-compatible clients.

## 🚀 Features

- **📊 Stock Information**: Complete company profiles, market metrics, and key statistics
- **📈 Historical Data**: Customizable historical price data with multiple timeframes
- **⚡ Real-time Quotes**: Live stock prices with change calculations
- **🔧 Technical Indicators**: 10+ professional-grade technical analysis tools
- **🚀 High Performance**: Intelligent caching system for optimal speed
- **🛡️ Robust**: Comprehensive error handling and validation
- **🔌 Easy Integration**: One-command installation for Claude Desktop

## 📦 Quick Installation

### For Claude Desktop Users

```bash
pip install finance-mcp-server
```

Then add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "finance": {
      "command": "finance-mcp-server"
    }
  }
}
```

Restart Claude Desktop and start asking about stocks! 🎉

### Manual Installation

```bash
# Clone the repository
git clone https://github.com/akshatbindal/finance-mcp-server.git
cd finance-mcp-server

# Install in development mode
pip install -e .

# Or install from PyPI
pip install finance-mcp-server
```

## 🎯 Usage Examples

Once installed, you can ask Claude Desktop natural language questions like:

- *"What's Apple's current stock price and market cap?"*
- *"Show me Tesla's performance over the last 6 months"*
- *"Calculate RSI and MACD for Microsoft stock"*
- *"Compare the 50-day moving average of Google vs Amazon"*
- *"What are the Bollinger Bands for Netflix right now?"*

## 🔧 Available Tools

### 📋 Stock Information
Get comprehensive company data including:
- Company name, sector, and industry
- Market capitalization and trading metrics
- P/E ratio, dividend yield, and beta
- 52-week highs and lows
- Volume and price data

```python
# Example: Get Apple stock information
{
  "symbol": "AAPL",
  "company_name": "Apple Inc.",
  "market_cap": 3000000000000,
  "current_price": 150.25,
  "pe_ratio": 25.5
}
```

### 📊 Historical Data
Retrieve historical stock data with flexible parameters:
- **Periods**: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
- **Intervals**: 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo

### ⚡ Real-time Data
Access current market data with:
- Live price updates
- Daily change and percentage change
- Current volume and trading metrics
- Automatic caching for performance

### 📈 Technical Indicators

| Indicator | Description | Use Case |
|-----------|-------------|----------|
| **SMA** | Simple Moving Average (20, 50, 200) | Trend identification |
| **EMA** | Exponential Moving Average (12, 26) | Responsive trend analysis |
| **RSI** | Relative Strength Index | Overbought/oversold conditions |
| **MACD** | Moving Average Convergence Divergence | Momentum and trend changes |
| **Bollinger Bands** | Volatility and price envelope | Support/resistance levels |
| **Stochastic** | Momentum oscillator | Entry/exit timing |
| **ATR** | Average True Range | Volatility measurement |
| **Volume SMA** | Volume moving average | Volume trend analysis |

## 🛠️ Configuration

### Basic Configuration
```json
{
  "mcpServers": {
    "finance": {
      "command": "finance-mcp-server"
    }
  }
}
```

### Advanced Configuration
```json
{
  "mcpServers": {
    "finance": {
      "command": "finance-mcp-server",
      "env": {
        "LOG_LEVEL": "INFO",
        "CACHE_DURATION": "300"
      }
    }
  }
}
```

## 🔧 Development

### Setting Up Development Environment

```bash
# Clone the repository
git clone https://github.com/akshatbindal/finance-mcp-server.git
cd finance-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Install development dependencies
pip install pytest black flake8 mypy

# Run tests
pytest

# Format code
black finance_mcp/

# Type checking
mypy finance_mcp/
```

### Running the Server

```bash
# Run directly
python -m finance_mcp.server

# Or use the console script
finance-mcp-server

# With debug logging
LOG_LEVEL=DEBUG finance-mcp-server
```

## 📊 Performance Features

### Intelligent Caching
- **Stock Info & Technical Indicators**: 5-minute cache
- **Real-time Data**: 1-minute cache
- **Historical Data**: Session-based caching
- Automatic cache invalidation

### Error Handling
- Graceful handling of invalid stock symbols
- Network timeout protection
- Comprehensive error messages
- Fallback mechanisms for data retrieval

## 🔒 Privacy & Security

- **No Data Storage**: All data is retrieved in real-time from Yahoo Finance
- **No User Tracking**: No personal information is collected or stored
- **Rate Limiting**: Built-in protection against API abuse
- **Error Isolation**: Errors don't crash the entire server

## 🤝 Contributing

We welcome contributions! Here's how you can help:

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make your changes** and add tests
4. **Run the test suite**: `pytest`
5. **Format your code**: `black finance_mcp/`
6. **Submit a pull request**

### Areas for Contribution
- Additional technical indicators
- Cryptocurrency support
- Options and futures data
- News sentiment integration
- Performance optimizations
- Documentation improvements

## 📋 Requirements

- **Python**: 3.8 or higher
- **Dependencies**:
  - `mcp >= 1.0.0` - Model Context Protocol framework
  - `yfinance >= 0.2.18` - Yahoo Finance API wrapper
  - `pandas >= 2.0.0` - Data manipulation and analysis
  - `ta >= 0.10.2` - Technical analysis library

## 🐛 Troubleshooting

### Common Issues

**Server not starting?**
```bash
# Check if all dependencies are installed
pip install -r requirements.txt

# Test the server manually
finance-mcp-server
```

**No data for a symbol?**
- Verify the stock symbol is correct (e.g., "AAPL" not "Apple")
- Check if the market is open (affects real-time data)
- Some symbols may not be available on Yahoo Finance

**Claude Desktop not connecting?**
- Ensure the configuration JSON is valid
- Check that the command path is correct
- Restart Claude Desktop completely
- Check Claude Desktop's logs for error messages

### Getting Help

- **GitHub Issues**: [Report bugs or request features](https://github.com/akshatbindal/finance-mcp-server/issues)
- **Discussions**: [Community support and questions](https://github.com/akshatbindal/finance-mcp-server/discussions)
- **Documentation**: [Full documentation and examples](https://github.com/akshatbindal/finance-mcp-server/wiki)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **Yahoo Finance** for providing free financial data
- **MCP Team** for the Model Context Protocol framework
- **Technical Analysis Library** contributors
- **Open Source Community** for inspiration and support

## 🔮 Roadmap

### Version 1.1.0 (Coming Soon)
- [ ] Cryptocurrency support (Bitcoin, Ethereum, etc.)
- [ ] Options chain data
- [ ] Earnings calendar integration
- [ ] News sentiment analysis

### Version 1.2.0 (Future)
- [ ] Portfolio tracking capabilities
- [ ] Custom indicator builder
- [ ] Multi-timeframe analysis
- [ ] Advanced charting data

### Version 2.0.0 (Vision)
- [ ] Machine learning predictions
- [ ] Risk analysis tools
- [ ] Backtesting framework
- [ ] Professional trader features

---

## ⭐ Star History

[![Star History Chart](https://api.star-history.com/svg?repos=akshatbindal/finance-mcp-server&type=Date)](https://star-history.com/#akshatbindal/finance-mcp-server&Date)

---

**Made with ❤️ for the MCP and trading communities**

*Bringing professional-grade financial analysis to conversational AI*
