📈 Finance MCP Server

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

Related MCP server: Stock Market Data and Technical Indicators MCP Server

📦 Quick Installation

For Claude Desktop Users

pip install finance-mcp-server

Then add to your Claude Desktop configuration:

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

Restart Claude Desktop and start asking about stocks! 🎉

Manual Installation

# 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

The Finance MCP Server exposes the following tools via the MCP protocol:

• get_comprehensive_stock_info: Get detailed company, market, financial, and analyst data for any stock symbol.

• get_historical_data: Retrieve historical price data with customizable period and interval, including splits/dividends.

• get_options_data: Fetch options chain data for a stock, including calls and puts for multiple expiration dates.

• get_institutional_holders: View institutional and major holders for a stock.

• get_earnings_calendar: Access earnings calendar, history, and analyst price targets.

• get_analyst_recommendations: Analyst recommendations, upgrades, and downgrades.

• get_financial_statements: Download full income statement, balance sheet, and cash flow (annual/quarterly).

• get_news: Latest news headlines and metadata for a stock.

• get_technical_analysis: Professional indicators (SMA, EMA, RSI, MACD, Bollinger Bands, volume, support/resistance, etc).

• get_sector_performance: Compare performance, volatility, and metrics for multiple stocks.

• get_dividend_history: Dividend payment history, summary, and stats.

Example Tool Call (MCP JSON)

{
  "tool": "get_comprehensive_stock_info",
  "arguments": {"symbol": "AAPL"}
}

Caching & Performance

• Company info, news, options, holders, calendar, recommendations: 5–60 min cache

• Real-time data: 1 min cache

• Fundamentals: 10 min cache

• Optimized yfinance usage: Multi-threading enabled, batch requests, and error isolation

Error Handling

• All endpoints return clear error messages on failure

• Graceful fallback for missing or partial data

• Logging for all exceptions and warnings

Technical Analysis

• Moving averages (SMA 20/50/200, EMA 12/26)

• RSI, MACD, Bollinger Bands, volume trends

• Support/resistance, volatility, and more

Expanded Data

• Options chain (calls/puts, OI, IV, last trade)

• Institutional/major holders

• Earnings calendar/history, analyst targets

• Full financial statements (annual/quarterly)

• News headlines, publisher, related tickers

• Dividend history and summary

🛠️ Configuration

Basic Configuration

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

Advanced Configuration

{
  "mcpServers": {
    "finance": {
      "command": "finance-mcp-server",
      "env": {
        "LOG_LEVEL": "INFO",
        "CACHE_DURATION": "300"
      }
    }
  }
}

🔧 Development

Setting Up Development Environment

# 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

# 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?

# 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

• Discussions: Community support and questions

• Documentation: Full documentation and examples

📄 License

This project is licensed under the Apache License - see the 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

Made with ❤️ for the MCP and trading communities

Bringing professional-grade financial analysis to conversational AI