FinMCP Core

Financial AI backend combining FastAPI, Google Gemini, and FastMCP. Exposes Yahoo Finance market data through an MCP stdio server and a Gemini-powered REST chat API for frontend clients.

Features

• MCP server (FinMCP-Core) — 15 tools for stock quotes, financials, risk metrics, news sentiment, SEC filings, and session summaries
• REST API — POST /api/chat endpoint powered by Gemini with automatic function calling
• Shared service layer — Yahoo Finance logic centralized in app/services/market_data.py
• Dual run modes — Web API or stdio MCP server from a single entry point
• Configurable Gemini model — set via GEMINI_MODEL in .env

Architecture

main.py
├── web  → FastAPI (app/api.py) → Gemini + fetch_stock_price
└── stdio → FastMCP (app/mcp_server.py) → 15 tools
                    ↓
         app/services/market_data.py (yfinance)

Layer	Role
app/services/market_data.py	Core yfinance business logic, returns structured dict payloads
app/mcp_server.py	Thin @mcp.tool() wrappers for MCP clients (Cursor, Claude Desktop)
app/api.py	FastAPI app with CORS; Gemini chat with fetch_stock_price

Prerequisites

• Python 3.10+
• Google AI API key (for the web chat API only)

Installation

git clone <your-repo-url>
cd finMCP

py -m pip install -r requirements.txt

Create a .env file in the project root:

GEMINI_API_KEY=your_key_here
GEMINI_MODEL=gemini-2.0-flash

Variable	Required	Description
GEMINI_API_KEY	Yes (web API)	API key from Google AI Studio
GEMINI_MODEL	No	Gemini model name (default: gemini-3.1-flash-lite)

The MCP stdio server does not require a Gemini API key.

Running

Web API (FastAPI)

py main.py web

Server starts at http://localhost:8000.

• Interactive docs: http://localhost:8000/docs
• Health check: GET /health

MCP Server (stdio)

py main.py

Runs the FinMCP-Core MCP server over stdio transport for desktop AI clients.

API Usage

POST /api/chat

Send a natural-language message. Gemini automatically calls fetch_stock_price when a stock quote is needed.

Request:

{
  "message": "What is the current price of AAPL?"
}

Response:

{
  "reply": "Apple Inc. (AAPL): 189.50 USD"
}

Example with curl:

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d "{\"message\": \"What is the current price of AAPL?\"}"

Gemini tools (web API)

Tool	Description
fetch_stock_price	Current price, currency, and company name for a ticker

API error responses

Status	Cause
400	Invalid request or unsupported model configuration
401	Invalid or unauthorized API key
429	Gemini rate limit or free-tier quota exceeded
500	GEMINI_API_KEY not configured
502	Transient or internal Gemini API error

The chat endpoint retries transient failures automatically via the Google SDK.

MCP Tools

Tool	Description
get_current_stock_price	Real-time price and company name
get_historical_stock_splits	Stock split history
get_stock_info	Sector, industry, market cap, description
get_financials	Income, balance sheet, or cash flow statements
get_dividend_analysis	Dividend yield, payout ratio, history
get_institutional_holders	Institutional ownership data
get_options_chain	Calls, puts, and implied volatility
get_news_sentiment	Filtered news with basic sentiment counts
get_valuation_metrics	P/E, PEG, EV/EBITDA, price-to-book
get_sector_comparison	Sector benchmarks and peers
get_risk_metrics	Beta, volatility, Sharpe ratio, max drawdown
get_earnings_analysis	EPS estimates vs actuals
get_sec_filings	SEC filing metadata
add_summary	Append a message to the session summary file
read_summary	Read accumulated session summaries

Session summaries are stored at app/data/summary.txt (created automatically on first use).

Cursor MCP Configuration

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "finmcp": {
      "command": "py",
      "args": ["main.py"],
      "cwd": "d:\\Desktop\\projects\\finMCP"
    }
  }
}

Adjust cwd to match your local project path.

Project Structure

finMCP/
├── app/
│   ├── __init__.py
│   ├── api.py              # FastAPI + Gemini chat endpoint
│   ├── mcp_server.py       # FastMCP tool registrations
│   ├── data/
│   │   └── summary.txt     # Created at runtime
│   └── services/
│       ├── __init__.py
│       └── market_data.py  # Yahoo Finance service functions
├── main.py                 # Entry point (web | stdio)
├── requirements.txt
└── .env                    # GEMINI_API_KEY, GEMINI_MODEL (not committed)

Troubleshooting

GEMINI_API_KEY is not configured

Set a valid key in .env. The MCP server does not need it.

429 / quota exceeded

Your API key has hit the free-tier or per-minute limit for the configured model. Options:

• Wait and retry (limits reset per minute/day)
• Switch model in .env, e.g. GEMINI_MODEL=gemini-1.5-flash
• Check usage at ai.dev/rate-limit

500 Internal error from Gemini

Often caused by an invalid model name. Use a supported Gemini model (not Gemma or other non-Gemini IDs). Set GEMINI_MODEL to a known working value such as gemini-2.0-flash or gemini-1.5-flash.

AttributeError: module 'collections' has no attribute 'Mapping'

Upgrade frozendict for Python 3.12+ compatibility:

py -m pip install --upgrade frozendict

py or pip not found

Use python and python -m pip instead, or install Python from python.org.

Dependencies

Package	Purpose
fastapi / uvicorn	Web API server
mcp	FastMCP stdio server
google-generativeai	Gemini chat with function calling
yfinance	Yahoo Finance market data
numpy	Risk metrics calculations
python-dotenv	Environment variable loading
pydantic	Request/response validation
httpx	HTTP client (transitive dependency)