使用说明

MCP金融服务器

一个模型上下文协议（MCP）服务器，它公开了8个由Supabase PostgreSQL支持的金融数据库工具。专为与Claude Desktop、MCP Inspector或任何兼容MCP的客户端一起使用而设计。

建筑

graph TB
    subgraph Client
        CD[Claude Desktop / MCP Client]
    end

    subgraph SRV[MCP Financial Server]
        M[main.py<br/>FastMCP Server]
        M --> CT[Company Tools]
        M --> FT[Financial Tools]
        M --> ST[Stock Tools]
        M --> AT[Analyst Tools]
        M --> SE[Sector Tools]

        CT --> V[Validators<br/>Pydantic]
        FT --> V
        ST --> V
        AT --> V
        SE --> V

        V --> Q[DB Queries<br/>PostgREST]
        Q --> C[Supabase Client]
    end

    subgraph DB[Supabase PostgreSQL]
        T1[companies]
        T2[financial_reports]
        T3[stock_prices]
        T4[analyst_ratings]
        T5[get_sector_stats RPC]
    end

    CD <-->|stdio / SSE| M
    C --> T1 & T2 & T3 & T4 & T5

可用工具

#	工具	说明	输入参数
1	`get_company_profile`	按股票代码或名称获取完整的公司简介	`identifier` （字符串）
2	`search_companies`	按部门、行业、市值或国家搜索公司	`sector?`, `industry?`, `min_market_cap?`, `max_market_cap?`, `country?`
3	`get_financial_report`	获取季度/年度财务报告	`ticker`, `fiscal_year?`, `fiscal_quarter?` （Q1-Q4）
4	`compare_companies`	并排比较2-5家公司	`tickers` （字符串[]）， `metrics?` （字符串[]）
5	`get_stock_price_history`	历史每日股票价格	`ticker`, `start_date?`, `end_date?`, `limit?` （默认值30）
6	`screen_stocks`	按财务标准筛选股票	`min_revenue?`, `min_eps?`, `min_gross_margin?`, `max_debt_to_equity?`, `sector?`
7	`get_analyst_ratings`	分析师评级和价格目标	`ticker`, `firm?`
8	`get_sector_overview`	综合部门统计	`sector` （必填）

先决条件

Python 3.11+ （用Python 3.14测试）
Supabase项目 --必须应用数据库模式（请参阅下面的步骤3）

快速开始

1.克隆存储库

git clone <repository-url>
cd mcp-financial-server

2.创建虚拟环境并安装依赖项

python3 -m venv .venv
source .venv/bin/activate    # On macOS/Linux
# .venv\Scripts\activate     # On Windows

pip install -e ".[dev]"

3.建立数据库

从以下位置运行SQL database/schema.sql 在Supabase SQL编辑器中：

首选 Supabase仪表板 >您的项目> SQL编辑器
复制并粘贴以下内容 database/schema.sql
点击跑

这将创建4个表(companies, financial_reports, stock_prices, analyst_ratings)以及a get_sector_stats RPC功能。

4.配置环境变量

cp .env.example .env

所有值均为 预填充 在 .env.example --默认的Supabase项目不需要编辑。

变量	是否预先填写？	描述
`SUPABASE_URL`	是	请提供项目URL
`SUPABASE_KEY`	是	输入匿名密钥
`MCP_TRANSPORT`	是	运输： `stdio` 或 `sse` （默认值： `stdio`)
`MCP_HOST`	是	SSE绑定主机（默认值： `0.0.0.0`)
`MCP_PORT`	是	SSE绑定端口（默认值： `8000`)
`RATE_LIMIT_RPM`	是	速率限制请求/分钟（默认值： `60`)

5.为数据库添加种子

source .venv/bin/activate   # if not already activated
python database/seed_script.py

这插入了25家公司、300份财务报告、约1600个股票价格和约60个分析师评级。

6.运行服务器

stdio模式 （适用于克劳德桌面）：

source .venv/bin/activate
python -m src.main

SSE模式 （适用于网络/远程客户端）：

source .venv/bin/activate
python -m src.main --transport sse --port 8000

流式HTTP模式 （适用于MCP检查员和现代客户）：

source .venv/bin/activate
python -m src.main --transport streamable-http --port 8000

MCP检查员 （交互式测试）：

source .venv/bin/activate
mcp dev src/main.py

提示： 您还可以使用附带的 run_server.sh 自动激活虚拟环境的脚本：
./run_server.sh                              # stdio (default)
./run_server.sh --transport sse --port 8000  # SSE
./run_server.sh --transport streamable-http  # Streamable HTTP

7.克劳德桌面配置

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "financial-server": {
      "command": "/path/to/mcp-financial-server/.venv/bin/python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/mcp-financial-server",
      "env": {
        "SUPABASE_URL": "https://grgtxcvpqwzxglrbkgro.supabase.co",
        "SUPABASE_KEY": "your-supabase-anon-key"
      }
    }
  }
}

工具调用示例

获取公司简介

Tool: get_company_profile
Args: {"identifier": "AAPL"}

搜索公司

Tool: search_companies
Args: {"sector": "Technology", "industry": "Software"}

财务报告

Tool: get_financial_report
Args: {"ticker": "MSFT", "fiscal_year": 2024, "fiscal_quarter": "Q4"}

比较公司

Tool: compare_companies
Args: {"tickers": ["AAPL", "MSFT", "GOOGL"], "metrics": ["revenue", "eps", "gross_margin"]}

股票价格历史

Tool: get_stock_price_history
Args: {"ticker": "NVDA", "start_date": "2024-10-01", "end_date": "2024-12-31"}

屏幕股票

Tool: screen_stocks
Args: {"sector": "Healthcare", "min_gross_margin": 40, "min_eps": 2.0}

分析师评级

Tool: get_analyst_ratings
Args: {"ticker": "TSLA", "firm": "Goldman Sachs"}

行业概况

Tool: get_sector_overview
Args: {"sector": "Energy"}

运行测试

source .venv/bin/activate
pytest tests/ -v

测试模拟Supabase客户端，包括：

输入验证（股票代码格式、日期格式、标识符、季度字符串、指标）
响应格式（货币、百分比、表格、比较）
错误处理（未找到公司，费率限制）
速率限制器行为
具有模拟DB响应的查询函数

项目结构

mcp-financial-server/
├── README.md               <- You are here
├── pyproject.toml           <- Dependencies & project config
├── .env.example             <- Environment variable template (pre-filled)
├── src/
│   ├── main.py              <- FastMCP entry point
│   ├── config/env.py        <- Pydantic Settings
│   ├── db/
│   │   ├── client.py        <- Supabase client singleton
│   │   └── queries.py       <- All DB query functions
│   ├── tools/
│   │   ├── company_tools.py <- get_company_profile, search_companies
│   │   ├── financial_tools.py <- get_financial_report, compare_companies
│   │   ├── stock_tools.py   <- get_stock_price_history, screen_stocks
│   │   ├── analyst_tools.py <- get_analyst_ratings
│   │   └── sector_tools.py  <- get_sector_overview
│   ├── validators/
│   │   └── input_validator.py <- Pydantic input models
│   └── utils/
│       ├── errors.py        <- Custom error classes
│       ├── formatters.py    <- Response text formatting
│       └── rate_limiter.py  <- Sliding-window rate limiter
├── database/
│   ├── schema.sql           <- Table definitions & RPC function
│   ├── seed.sql             <- SQL fallback seed data
│   └── seed_script.py       <- Python seed script
└── tests/
    └── test_tools.py        <- Unit tests with mocked DB

安全

无SQL注入：所有查询都使用Supabase PostgREST客户端，该客户端会自动参数化值
输入验证：在查询之前，每个工具输入都通过Pydantic进行验证
速率限制：内存中的滑动窗口限制器可防止滥用SSE传输
Env分离：从加载的秘密 .env 文件，从未硬编码

许可证

麻省理工学院