Finance Intelligence MCP Server
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.
Finance Intelligence MCP Server
A production-grade, asynchronous Model Context Protocol (MCP) server that grants AI assistants (Claude Desktop, Cursor, ChatGPT, VS Code, etc.) access to real-time financial market data, company metrics, and history.
Powered by FastMCP, yfinance, and Pydantic, this server uses advanced thread-offloading, caching, and robust error isolation to provide standard JSON-RPC tools with zero crashes.
Architecture Overview
+--------------------------------------+
| LLM Client (e.g. Claude Desktop) |
+------------------+-------------------+
|
| (JSON-RPC over stdio / SSE)
v
+------------------+-------------------+
| Finance Intelligence MCP |
| |
| +------------------------------+ |
| | server.py | |
| +--------------+---------------+ |
| | |
| v |
| +------------------------------+ |
| | tools (stocks / companies) | |
| +--------------+---------------+ |
| | |
| v |
| +------------------------------+ |
| | clients/yahoo.py | |
| | (Thread Pool & TTL Cache) | |
| +--------------+---------------+ |
+------------------|-------------------+
|
v (asyncio.to_thread)
+------------------+-------------------+
| Yahoo Finance Service |
+--------------------------------------+Key Design Decisions
Async Thread Pool Execution
yfinanceis fundamentally a blocking synchronous library. Directly calling it in async tool handlers would block the event loop, freezing the MCP server. We offload everyyfinancecall to a thread pool viaasyncio.to_thread.In-Memory TTL Caching To prevent Yahoo Finance rate limits and reduce tool latency during conversational loops, we implement a thread-safe, in-memory cache with a configurable TTL (default: 5 minutes) for ticker info and history query responses.
Safe Log Handling Stdout (
sys.stdout) is strictly reserved for the MCP JSON-RPC protocol transport. Standard logs are redirected entirely to stderr (sys.stderr) using a custom structured logger to prevent channel corruption.Crash-Resilient Tool Handlers Every tool is wrapped in strict try-except blocks. Instead of crashing the server, exceptions (e.g., TickerNotFound, network timeouts) are caught, logged, and returned as structured JSON error responses.
Related MCP server: trade-mcp
Features & Available MCP Tools
The server exposes 5 standardized tools:
Tool Name | Parameters | Description | Returns |
|
| Search for matching company names, tickers, and exchanges | JSON array of results |
|
| Retrieve real-time pricing and basic exchange details | Current price, state, currency, time |
|
| Retrieve key fundamentals, stats, and company info | Market cap, P/E, beta, dividend yield, etc. |
|
| Side-by-side metric comparison of two tickers | Structured comparative matrix |
|
| Download historical prices (1d, 5d, 1mo, 3mo, 6mo, 1y, 5y, max) | Chronological price records |
Installation
Prerequisites
Python 3.12 or newer
Virtual Environment or
uvpackage manager
Standard Setup
Clone the repository:
git clone https://github.com/yourusername/finance-intelligence-mcp.git cd finance-intelligence-mcpCreate a virtual environment and install dependencies:
python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -e ".[dev]"Configure the environment: Create a
.envfile from the example:cp .env.example .env(Adjust values like
CACHE_TTL_SECONDSorLOG_LEVELif needed.)
Usage
Running Locally
To run the server in the default stdio mode (which local clients like Claude Desktop use):
python -m src.mainTo run the server in SSE (HTTP) mode:
python -m src.main --transport sse --port 8000Client Integration Configurations
1. Claude Desktop Configuration
Add the following to your Claude Desktop configuration file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):
Standard Execution (Python Venv):
{
"mcpServers": {
"finance-intelligence": {
"command": "/Users/YOUR_USER/Desktop/finance mcp/.venv/bin/python",
"args": [
"-m",
"src.main"
],
"env": {
"LOG_LEVEL": "INFO",
"CACHE_TTL_SECONDS": "300"
}
}
}
}Docker Execution:
{
"mcpServers": {
"finance-intelligence-docker": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"finance-intelligence-mcp:latest"
]
}
}
}2. Cursor Configuration
To add the server to Cursor:
Open Cursor Settings -> Features -> MCP.
Click + Add New MCP Server.
Fill out the fields:
Name:
Finance IntelligenceType:
commandCommand:
/path/to/project/.venv/bin/python -m src.main
Docker Containerization
Build the image:
docker build -t finance-intelligence-mcp:latest .Run the image locally in stdio mode:
docker run -i --rm finance-intelligence-mcp:latestRun the image locally in HTTP/SSE mode:
docker run -d -p 8000:8000 --name finance-mcp finance-intelligence-mcp:latest --transport sse --port 8000
Example Prompts
Here are some prompt examples you can ask your AI model once the server is connected:
Search: "Find the stock ticker for Nvidia." -> Triggers
search_company(query="Nvidia")Price: "What is the current stock price and market state of Apple (AAPL)?" -> Triggers
get_stock_price(symbol="AAPL")Info: "Show me the key financials for Microsoft, including market cap, beta, and P/E ratio." -> Triggers
get_stock_info(symbol="MSFT")Comparison: "Compare Apple and Microsoft stocks side by side." -> Triggers
compare_companies(symbol1="AAPL", symbol2="MSFT")History: "Analyze the historical performance of Tesla (TSLA) over the past month." -> Triggers
get_stock_history(symbol="TSLA", period="1mo")
Quality & Testing
We enforce code quality through automated checks.
Run Tests
pytest tests/ -vRun Linter
ruff check src/ tests/Run Type Checker
mypy src/Roadmap
Roadmap
Stock prices
Company information
Stock comparison
Financial statements
Crypto support
Macroeconomic indicators
Portfolio analysis
DCF valuation
Contributing
Contributions are welcome! Please open an issue or submit a pull request with any suggestions or improvements. Make sure to run the formatting and test suite before submitting code.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for Financial Modeling Prep API with 250+ financial data tools
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Official Intrinio MCP server. US stock prices, options and fundamentals for AI agents.
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.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that exposes comprehensive Yahoo Finance data (quotes, financials, options, news, and more) to AI agents via the yfinance library, requiring no API key.24MIT
- AlicenseAqualityDmaintenanceAn advanced MCP server for real-time worldwide stock market data, technical indicators, financials, news, and Python sandboxing with AI models, supporting US and Indian markets.291MIT
- FlicenseNot gradedqualityDmaintenanceA production-grade MCP server that provides tools to fetch historical stock data, company information, and technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands) via yfinance, and includes a Flask web dashboard for visual analysis.-
- FlicenseNot gradedqualityDmaintenanceProduction-grade MCP server that enables AI assistants to access real-time financial market data with intelligent fallback mechanisms, supporting stock prices, comparisons, fundamentals, and market summaries via Yahoo Finance and CSV.-