FinMCP-Backend

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

Related MCP server: yfinance

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)

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

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)

API error responses

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

MCP Tools

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