Skip to main content
Glama

findata-mcp

一个统一的金融数据库,带有MCP服务器,供编写代码的代理使用。

当代理查询MCP(例如"equity daily prices")时,它会收到:

  • findata包装函数签名

  • 完整的参数和返回类型文档

  • 一个可直接粘贴的调用我们API的代码示例

MCP从不获取实时数据——它是一个文档服务器,以便代理能够编写对findata库的正确调用。


项目结构

data-mcp/
├── findata/                         Data library
│   ├── equity_prices.py             get_equity_prices()           yfinance wrapper
│   ├── sp500_composition.py         get_sp500_composition()       fja05680/sp500 (local git clone)
│   ├── fama_french.py               get_fama_french_factors()     Ken French Data Library
│   ├── fred.py                      get_fred_series()             FRED macroeconomic series
│   ├── cboe_volatility.py           get_cboe_volatility_indices() VIX / VVIX
│   ├── coingecko.py                 get_coingecko_ohlcv()         CoinGecko public API
│   ├── file_reader.py               get_file_data()               CSV / Parquet / Excel
│   └── bloomberg.py                 get_bloomberg_ticks()         blpapi — tick-by-tick
│                                    get_bloomberg_bars()          blpapi — intraday OHLCV
│                                    get_bloomberg_data()          blpapi — historical / reference
├── findata_mcp/
│   └── server.py                    Tool registry + MCP handlers
├── Dockerfile
├── docker-compose.yml
├── .github/workflows/docker.yml     GHCR build + push on every push to main
├── pyproject.toml
└── README.md

Related MCP server: FinData MCP

安装

运行findata-mcp的推荐方式是通过Docker。该镜像在每次推送到main时发布到GHCR,并内置了Codex CLI。

先决条件

  • Docker

  • 在主机上认证的Codex

1. 认证Codex(一次性)

codex auth login    # opens browser → saves to ~/.codex/auth.json

2. 拉取并运行

curl -O https://raw.githubusercontent.com/lakshya-aga/data-mcp/main/docker-compose.yml
docker compose up -d

docker-compose.yml以只读方式挂载~/.codex,因此容器继承您的Codex会话,无需交互式提示。命名卷可在重启后保留生成的文件和数据。

3. 验证

docker logs data-mcp-findata-mcp-1
# should show: findata-mcp starting on :8000

连接到服务器

Claude Desktop

添加到~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "findata": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Python(原始MCP客户端)

import asyncio
from mcp.client.sse import sse_client
from mcp.client.session import ClientSession

async def main():
    async with sse_client("http://localhost:8000/sse") as (r, w):
        async with ClientSession(r, w) as s:
            await s.initialize()
            res = await s.call_tool("search_tools", {"query": "equity daily prices", "top_k": 3})
            print(res.content[0].text)

asyncio.run(main())

OpenAI Agents SDK

from agents.mcp import MCPServerSse
mcp = MCPServerSse(url="http://localhost:8000/sse")

MCP工具

Tool

Description

search_tools

自然语言查询 → 匹配的函数文档 + 代码示例

get_tool_doc

按确切名称获取一个函数的完整参考

list_all_tools

所有包装函数及其摘要和标签

request_data_source

请求Codex实现并注册新的数据包装器

res = await s.call_tool("search_tools", {"query": "fama french factors", "top_k": 2})

get_tool_doc

res = await s.call_tool("get_tool_doc", {"tool_name": "get_equity_prices"})

request_data_source

res = await s.call_tool("request_data_source", {
    "description": "get World Bank GDP per capita using the wbdata library"
})

Codex编写findata/<module>.py,更新server.py,并将新函数热重载到实时注册表中——无需重启。


环境变量

Variable

Description

OPENAI_API_KEY

Codex认证——如果设置则跳过OAuth(替代主机认证挂载)

FRED_API_KEY

get_fred_series必需。免费获取于 fred.stlouisfed.org

CODEX_CLI_PATH

覆盖Codex二进制路径(默认为PATH上的codex)

BLOOMBERG_HOST

get_bloomberg_*函数的Bloomberg API主机(默认localhost)

BLOOMBERG_PORT

Bloomberg API端口(默认8194)

BLOOMBERG_TIMEOUT_MS

在放弃Bloomberg请求之前每个事件的等待时间(默认30000)

BLOOMBERG_AUTH

用于Server API / B-PIPE的setAuthenticationOptions字符串,例如AuthenticationType=OS_LOGON。对于桌面终端,请留空。


findata快速参考

get_equity_prices

from findata.equity_prices import get_equity_prices

df = get_equity_prices(
    tickers=["AAPL", "MSFT"],
    start_date="2024-01-01",
    end_date="2024-12-31",
    fields=["Close"],
    frequency="1d",         # 1d 5d 1wk 1mo 3mo
)

get_fama_french_factors

from findata.fama_french import get_fama_french_factors

df = get_fama_french_factors(factor_model="5", start_date="2010-01-01", end_date="2020-12-31")
# columns: Mkt-RF, SMB, HML, RMW, CMA, RF

get_fred_series

from findata.fred import get_fred_series

df = get_fred_series(["CPIAUCSL", "UNRATE"], start_date="2015-01-01", end_date="2024-12-31")

get_coingecko_ohlcv

from findata.coingecko import get_coingecko_ohlcv

df = get_coingecko_ohlcv("bitcoin", vs_currency="usd", days=90)
# columns: open, high, low, close, volume

get_cboe_volatility_indices

from findata.cboe_volatility import get_cboe_volatility_indices

df = get_cboe_volatility_indices(symbols=["^VIX", "^VVIX"], start_date="2020-01-01", end_date="2024-12-31")

get_sp500_composition

from findata.sp500_composition import get_sp500_composition

members = get_sp500_composition("2024-12-31")   # list[str], ~503 tickers

get_bloomberg_ticks — 任何证券的tick级数据

需要Bloomberg终端、SAPI或B-PIPE权限以及SDK:

pip install blpapi --index-url https://bcms.bloomberg.com/pip/simple/
from findata.bloomberg import get_bloomberg_ticks

# Every trade print in one US cash session, in New York time
ticks = get_bloomberg_ticks(
    "AAPL US Equity",
    "2024-06-03 09:30:00",
    "2024-06-03 16:00:00",
    tz="America/New_York",
)
# index = time (tz-aware)
# columns: security, type, value, size, conditionCodes, exchangeCode

# Trades AND top-of-book quotes, one hour per sub-request
book = get_bloomberg_ticks(
    "ESZ5 Index",
    "2024-06-03 13:30:00",
    "2024-06-03 20:00:00",
    event_types=["TRADE", "BID", "ASK"],
    chunk="1h",
)

# VWAP straight from the prints
trades = ticks[ticks["type"] == "TRADE"]
vwap = (trades["value"] * trades["size"]).sum() / trades["size"].sum()

安全字符串原样传递给Bloomberg,因此终端引用的任何内容都有效——"AAPL US Equity"、"ESZ5 Index"、"EURUSD Curncy"、"TY1 Comdty"、"US912810TW33 Govt"。

长窗口被切成chunk大小的子请求(默认一天)并拼接起来,因为Bloomberg会静默截断过大的日内响应而不是报错。Bloomberg自身的限制仍然适用:日内tick历史大约可回溯140天,每日成交量上限与您的权限相关。

在遍历一个证券池时重用同一个会话——这样可以避免每个名称都进行连接握手:

from findata.bloomberg import BloombergSession, get_bloomberg_ticks

with BloombergSession() as bbg:
    frames = {
        sym: get_bloomberg_ticks(sym, start, end, session=bbg)
        for sym in universe
    }

在本地将tick聚合成K线,支持任意pandas偏移:

from findata.bloomberg import ticks_to_bars

bars = ticks_to_bars(ticks, rule="5min")
# columns: open, high, low, close, ticks, volume, vwap

get_bloomberg_bars

from findata.bloomberg import get_bloomberg_bars

# 5-minute bars, aggregated server-side (much lighter than raw ticks)
bars = get_bloomberg_bars(
    "AAPL US Equity",
    "2024-06-03 09:30:00",
    "2024-06-03 16:00:00",
    interval=5,                 # minutes, 1-1440
    tz="America/New_York",
)
# columns: security, open, high, low, close, volume, numEvents, value

get_bloomberg_data

from findata.bloomberg import get_bloomberg_data

# Historical daily series -> MultiIndex columns (field, security)
df = get_bloomberg_data(
    tickers=["AAPL US Equity", "MSFT US Equity"],
    fields=["PX_LAST", "VOLUME"],
    start_date="2024-01-01",
    end_date="2024-12-31",
)
close = df["PX_LAST"]

# Reference data -> rows=securities, cols=fields
ref = get_bloomberg_data(
    tickers=["AAPL US Equity"],
    fields=["CUR_MKT_CAP", "GICS_SECTOR_NAME"],
    request_type="ReferenceDataRequest",
    overrides={"BEST_FPERIOD_OVERRIDE": "1BF"},
)

get_file_data

from findata.file_reader import get_file_data

df = get_file_data("data/prices.parquet", tickers=["AAPL"], start_date="2023-01-01", end_date="2023-12-31")

测试

pytest tests/ -v

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A specialized MCP server that provides institutional-grade financial data and market research via the Finnhub API. It enables AI agents to function as equity researchers, generating professional market reports and high-fidelity analysis for stock tickers.
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      FinData MCP gives AI agents access to market data, company fundamentals, and macroeconomic indicators via MCP. It covers stocks, ETFs, crypto, forex, commodities, and economic time series.
      5
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides AI agents with financial tools including real-time quotes, backtesting, technical analysis, and multi-exchange data via a simple CLI interface.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI agents to query real-time financial data including stock quotes, market indices, company fundamentals, and portfolio tracking.
      MIT