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 인증(1회)

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 도구

도구

설명

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를 업데이트하며 새 함수를 라이브 레지스트리에 핫 리로드합니다. 재시작이 필요 없습니다.


환경 변수

변수

설명

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 — 모든 증권에 대한 틱 수준 데이터

Bloomberg Terminal, 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 자체 제한은 여전히 적용됩니다: 일중 틱 기록은 약 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
    }

틱을 로컬에서 임의의 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