FinMCP-Core
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 summariesREST API —
POST /api/chatendpoint powered by Gemini with automatic function callingShared service layer — Yahoo Finance logic centralized in
app/services/market_data.pyDual run modes — Web API or stdio MCP server from a single entry point
Configurable Gemini model — set via
GEMINI_MODELin.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)Layer | Role |
| Core yfinance business logic, returns structured |
| Thin |
| FastAPI app with CORS; Gemini chat with |
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.txtCreate a .env file in the project root:
GEMINI_API_KEY=your_key_here
GEMINI_MODEL=gemini-2.0-flashVariable | Required | Description |
| Yes (web API) | API key from Google AI Studio |
| No | Gemini model name (default: |
The MCP stdio server does not require a Gemini API key.
Running
Web API (FastAPI)
py main.py webServer starts at http://localhost:8000.
Interactive docs: http://localhost:8000/docs
Health check:
GET /health
MCP Server (stdio)
py main.pyRuns 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 |
| Current price, currency, and company name for a ticker |
API error responses
Status | Cause |
| Invalid request or unsupported model configuration |
| Invalid or unauthorized API key |
| Gemini rate limit or free-tier quota exceeded |
|
|
| Transient or internal Gemini API error |
The chat endpoint retries transient failures automatically via the Google SDK.
MCP Tools
Tool | Description |
| Real-time price and company name |
| Stock split history |
| Sector, industry, market cap, description |
| Income, balance sheet, or cash flow statements |
| Dividend yield, payout ratio, history |
| Institutional ownership data |
| Calls, puts, and implied volatility |
| Filtered news with basic sentiment counts |
| P/E, PEG, EV/EBITDA, price-to-book |
| Sector benchmarks and peers |
| Beta, volatility, Sharpe ratio, max drawdown |
| EPS estimates vs actuals |
| SEC filing metadata |
| Append a message to the session summary file |
| 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-flashCheck 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 frozendictpy or pip not found
Use python and python -m pip instead, or install Python from python.org.
Dependencies
Package | Purpose |
| Web API server |
| FastMCP stdio server |
| Gemini chat with function calling |
| Yahoo Finance market data |
| Risk metrics calculations |
| Environment variable loading |
| Request/response validation |
| HTTP client (transitive dependency) |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Hosted MCP server for Indian NSE/BSE stock research: 59 tools for quotes, financials and ratios, peers, shareholding and pledge, filings with extracted facts, screens, F&O and FII/DII context. Source and freshness on every answer; no buy/sell calls.
Financial data MCP server for Claude, ChatGPT, Cursor and Codex. Real-time stock quotes, financial statements, options flow, SEC filings, insider trades, 13F holdings, macro data and market news from gloom.sh, the open-source Bloomberg Terminal alternative.
MCP server for Financial Modeling Prep API with 250+ financial data tools
Official Intrinio MCP server. US stock prices, options and fundamentals for AI agents.
Related MCP Servers
- AlicenseCqualityDmaintenanceA Model Context Protocol server providing comprehensive financial data from Yahoo Finance, allowing users to retrieve detailed stock information, financial statements, options data, and market news.34MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server that provides comprehensive access to Yahoo Finance data through 18 specialized tools for pricing, financials, options, holders, and news.1836 PyPI1MIT
- AlicenseAqualityBmaintenanceMCP server that exposes Yahoo Finance data through tools for searching instruments, fetching quotes, history, company info, financials, dividends, news, recommendations, and options. Enables AI assistants to answer market-data questions using natural language.24726 PyPI2MIT
- FlicenseNot gradedqualityCmaintenanceMCP server wrapping yfinance to provide stock market data, financials, and analytics via 24 tools.-