# FinMCP 📈 — Financial Data MCP Server

> *Let any AI agent query stocks, financials, markets & portfolios in real time.*

[![CI](https://github.com/USERNAME/FinMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/USERNAME/FinMCP/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/finmcp)](https://pypi.org/project/finmcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)
[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## 🚀 What is FinMCP?

**FinMCP** is an open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives any AI agent — Claude, Codex, Cursor, Hermes, or custom agents — **real-time superpowers over financial data**.

Ask your AI agent questions like:

> *"What's Apple's current stock price and P/E ratio?"*
> *"Show me my portfolio performance today"*
> *"Compare Nvidia vs AMD on revenue growth"*
> *"What's the NIFTY 50 doing right now?"*
> *"Get the latest earnings transcript sentiment for Tesla"*

And it queries live financial data — no API keys required. 🎯

---

## ✨ Features

| Feature | Description |
|---|---|
| **🏷️ Stock Quotes** | Real-time price, change %, volume, market cap, day range |
| **📜 Historical Prices** | OHLCV data — 1d to max, any interval |
| **🏢 Company Fundamentals** | Profile, sector, financials, ratios, employees |
| **📊 Financial Statements** | Income statement, balance sheet, cash flow (annual/quarterly) |
| **🌍 Market Indices** | S&P 500, NASDAQ, NIFTY 50, SENSEX, FTSE, DAX, Nikkei & more |
| **💱 Currency Exchange** | Live FX rates for 150+ currencies |
| **📰 Market News** | Latest financial news for any ticker |
| **📁 Portfolio Tracker** | Track holdings, P&L, allocation, performance |
| **⚖️ Stock Comparison** | Side-by-side comparison of key metrics |
| **🔍 Ticker Search** | Find tickers by company name or keyword |

> 🌏 **Global markets supported** — US, India (`.NS`), Europe, Japan, and more.

---

## 🏁 Quick Start

### Prerequisites

- Python 3.10+
- An MCP-compatible client: [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex CLI](https://github.com/openai/codex), [Hermes Agent](https://hermes-agent.nousresearch.com), or [Cursor](https://cursor.com)

### 1️⃣ Install

```bash
pip install finmcp
# or with uv (faster)
uv pip install finmcp
# or from source
git clone https://github.com/USERNAME/FinMCP.git
cd FinMCP
uv sync
```

### 2️⃣ Run the server

```bash
# Run in stdio mode (default — for MCP clients)
finmcp

# Or run as SSE server (for remote connections)
finmcp --transport sse --port 9876
```

### 3️⃣ Connect your AI agent

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "finmcp": {
      "command": "finmcp",
      "args": []
    }
  }
}
```

#### Claude Code

```bash
claude mcp add finmcp -- cmd finmcp
```

#### Hermes Agent

Run alongside your agent:

```bash
finmcp
```

Then in your Hermes config, add it as an MCP server.

---

## 🛠️ Tools Reference

### Stock Data

| Tool | Args | Returns |
|---|---|---|
| `get_stock_quote` | `ticker` | Price, change, volume, market cap, P/E, dividend yield |
| `get_historical_prices` | `ticker`, `period`, `interval` | OHLCV time series with summary stats |
| `get_company_info` | `ticker` | Full company profile, sector, financial ratios |
| `get_financials` | `ticker`, `statement_type`, `annual` | Income statement / balance sheet / cash flow |
| `search_tickers` | `query`, `limit` | Matching tickers with names, exchange, sector |

### Market Data

| Tool | Args | Returns |
|---|---|---|
| `get_market_indices` | *(none)* | Values for 13 major global indices |
| `get_currency_rates` | `base` | FX rates for 15+ major currencies |
| `get_market_news` | `ticker` (opt), `max_articles` | Latest news articles with links |

### Portfolio & Analysis

| Tool | Args | Returns |
|---|---|---|
| `track_portfolio` | `holdings_json`, `invest_currency` | Portfolio value, P&L, allocation breakdown |
| `compare_stocks` | `tickers_json` | Side-by-side comparison of 2-10 stocks |

---

## 💡 Example Queries

Ask your AI agent (once FinMCP is connected):

```
User: "What's the current state of the Indian market?"
Agent: *uses get_market_indices → sees NIFTY 50 and SENSEX*
Agent: *uses get_stock_quote for RELIANCE.NS, TCS.NS, HDFCBANK.NS*

User: "How did my portfolio do today?"
Agent: *uses track_portfolio with your holdings*

User: "Find me good AI stocks to invest in"
Agent: *uses search_tickers to find AI companies*
Agent: *uses compare_stocks to compare them*

User: "Show me Microsoft's revenue trend"
Agent: *uses get_financials for MSFT income statement*
```

---

## 🐍 Python API

Use FinMCP programmatically in your own agents:

```python
from finmcp.server import server

# Run the MCP server
server.run(transport="stdio")
```

Or import individual tool functions:

```python
from finmcp.server import get_stock_quote
import json

result = json.loads(get_stock_quote("AAPL"))
print(f"Apple: ${result['price']} ({result['change_percent']:+.2f}%)")
```

---

## 🧪 Development

```bash
# Clone and set up
git clone https://github.com/USERNAME/FinMCP.git
cd FinMCP
uv sync

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/

# Type check
uv run mypy src/
```

---

## 📋 Roadmap

- [ ] **Earnings transcripts** — AI-powered sentiment analysis of earnings calls
- [ ] **Technical indicators** — SMA, RSI, MACD, Bollinger Bands
- [ ] **Options data** — Option chains, Greeks, implied volatility
- [ ] **Crypto prices** — Bitcoin, Ethereum, and major cryptocurrencies
- [ ] **SEC filings** — Fetch 10-K, 10-Q, 8-K filings for any company
- [ ] **Chart generation** — Generate price charts as SVG/PNG
- [ ] **Alert system** — Price alerts and threshold notifications
- [ ] **Web UI** — Dashboard with charts and portfolio overview

---

## 🤝 Contributing

PRs are welcome! Check the [roadmap](#-roadmap) for ideas, or suggest your own.

1. Fork the repo
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a PR

---

## 📄 License

MIT — use it freely in personal and commercial projects.

---

## ⭐️ Show Your Support

If FinMCP helps you, please give it a ⭐️ on GitHub — it helps others discover it too!

---

*Built with ❤️ by [Jayesh](https://github.com/USERNAME)*