FinMCP

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

CI PyPI version Python 3.10+ MCP MIT License

---

🚀 What is FinMCP?

FinMCP is an open-source Model Context Protocol (MCP) 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, Claude Code, Codex CLI, Hermes Agent, or Cursor

1️⃣ Install

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

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

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

Claude Code

claude mcp add finmcp -- cmd finmcp

Hermes Agent

Run alongside your agent:

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:

from finmcp.server import server

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

Or import individual tool functions:

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

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