Finance MCP Server

A Model Context Protocol (MCP) server written in Dart that integrates with SEC EDGAR to provide comprehensive financial data and analysis tools for Large Language Models.

This server enables LLMs to fetch company metadata, historical financial statements (up to 10 years), and SEC filings (10-K, 10-Q, 8-K) for sentiment analysis and fundamental research.

Features

Company Metadata: Resolve tickers to CIKs and company names.
Financial Statements: Retrieve up to 10 years of Balance Sheets, Income Statements, and Cash Flows with computed metrics (ROE, ROIC).
SEC Filings: Access full text content of 8-K, 10-K, and 10-Q filings for sentiment analysis (compliant with SEC User-Agent requirements).
Analysis Prompts: Built-in prompts for comprehensive_analysis and compare_stocks to guide LLMs in structured financial reporting.
Flexible Transports: Supports stdio (default) for local clients and http (SSE) for remote deployment.
Docker Support: Ready-to-use Dockerfile for containerized deployment.

Installation

Option 1: Global Activation (Recommended)

Install globally from pub.dev to use the CLI anywhere:

dart pub global activate finance_mcp

Option 2: From Source

For development or contributing:

git clone https://github.com/leehack/finance-mcp.git
cd finance_mcp
dart pub get

Usage

Running the Server

1. Stdio Transport (Default) Ideal for local use with clients like Claude Desktop.

# If installed globally:
finance_mcp
# OR
dart pub global run finance_mcp

# If from source:
dart run bin/server.dart

2. HTTP Transport (SSE) Exposes an SSE endpoint for remote connections.

dart run bin/server.dart --transport http --port 3000

The server will listen on http://0.0.0.0:3000/mcp.

Configuration

To use with Claude Desktop, add the following to your mcp.json:

1. Using Global Installation (Simplest)

{
  "mcpServers": {
    "finance-mcp": {
      "command": "dart",
      "args": ["pub", "global", "run", "finance_mcp"]
    }
  }
}

2. Using Docker

{
  "mcpServers": {
    "finance-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "finance-mcp"]
    }
  }
}

3. Using Source (Development)

{
  "mcpServers": {
    "finance-mcp": {
      "command": "dart",
      "args": ["run", "/ABSOLUTE/PATH/TO/finance-mcp/bin/server.dart"]
    }
  }
}

Advanced: Auto-Updating Global Install

To automatically update finance_mcp every time you run it (adds latency):

Click to see configuration

macOS / Linux:

{
  "mcpServers": {
    "finance-mcp": {
      "command": "/bin/sh",
      "args": [
        "-c",
        "dart pub global activate finance_mcp 1>&2 && $HOME/.pub-cache/bin/finance_mcp"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "finance-mcp": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "dart pub global activate finance_mcp > NUL && %LOCALAPPDATA%\\Pub\\Cache\\bin\\finance_mcp.bat"
      ]
    }
  }
}

Available Tools

get_company_info:
- ticker: Stock ticker symbol (e.g., AAPL).
- Returns CIK, name, and exchange info.
get_financial_statements:
- ticker: Stock ticker symbol.
- period: annual or quarterly (default: annual).
- year: Specific year (optional).
- years: Number of years to fetch (default: 5).
- Returns structured JSON of financial statements.
get_sec_filings:
- ticker: Stock ticker symbol.
- forms: List of forms to fetch (e.g., ["10-K", "8-K"]).
- limit: Max number of filings.
- includeContent: Boolean to fetch full text body (default: false).

Development

Run tests:

dart test

License

See LICENSE.

SEC EDGAR