FinMCP 📈 — Financial Data MCP Server

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

🚀 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. 🎯

Related MCP server: Stock Market Real-Time Analyzer

✨ Features

🌏 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

Market Data

Portfolio & Analysis

💡 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