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

1. Async Thread Pool Execution yfinance is fundamentally a blocking synchronous library. Directly calling it in async tool handlers would block the event loop, freezing the MCP server. We offload every yfinance call to a thread pool via asyncio.to_thread.

2. 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.

3. 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.

4. 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:

Installation

Prerequisites

• Python 3.12 or newer

• Virtual Environment or uv package manager

Standard Setup

1. Clone the repository:

   git clone https://github.com/yourusername/finance-intelligence-mcp.git
   cd finance-intelligence-mcp

2. Create a virtual environment and install dependencies:

   python3 -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip
   pip install -e ".[dev]"

3. Configure the environment: Create a .env file from the example:

   cp .env.example .env

   (Adjust values like CACHE_TTL_SECONDS or LOG_LEVEL if needed.)

Usage

Running Locally

To run the server in the default stdio mode (which local clients like Claude Desktop use):

python -m src.main

To run the server in SSE (HTTP) mode:

python -m src.main --transport sse --port 8000

Client 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:

1. Open Cursor Settings -> Features -> MCP.

2. Click + Add New MCP Server.

3. Fill out the fields:

   • Name: Finance Intelligence

   • Type: command

   • Command: /path/to/project/.venv/bin/python -m src.main

Docker Containerization

1. Build the image:

   docker build -t finance-intelligence-mcp:latest .

2. Run the image locally in stdio mode:

   docker run -i --rm finance-intelligence-mcp:latest

3. Run 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/ -v

Run 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.