findata-mcp
findata-mcp
Una biblioteca unificada de datos financieros con un servidor MCP para agentes que escriben código.
Cuando un agente consulta el MCP (por ejemplo, "equity daily prices"), recibe:
La firma de la función wrapper de findata
Documentación completa de parámetros y tipos de retorno
Un ejemplo de código listo para pegar que llama a nuestra API
El MCP nunca obtiene datos en vivo: es un servidor de documentación para que los agentes puedan escribir llamadas correctas a la biblioteca findata.
Estructura del proyecto
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.mdRelated MCP server: FinData MCP
Instalación
La forma recomendada de ejecutar findata-mcp es mediante Docker. La imagen se publica en GHCR en cada push a main e incluye Codex CLI integrado.
Requisitos previos
Docker
Codex autenticado en tu máquina host
1. Autenticar Codex (una vez)
codex auth login # opens browser → saves to ~/.codex/auth.json2. Descargar y ejecutar
curl -O https://raw.githubusercontent.com/lakshya-aga/data-mcp/main/docker-compose.yml
docker compose up -ddocker-compose.yml monta ~/.codex en modo solo lectura para que el contenedor herede tu sesión de Codex sin avisos interactivos. Los volúmenes con nombre conservan los archivos generados y los datos entre reinicios.
3. Verificar
docker logs data-mcp-findata-mcp-1
# should show: findata-mcp starting on :8000Conexión al servidor
Claude Desktop
Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"findata": {
"url": "http://localhost:8000/sse"
}
}
}Python (cliente MCP sin procesar)
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")Herramientas MCP
Tool | Description |
| Consulta en lenguaje natural → documentación de funciones coincidentes + ejemplos de código |
| Referencia completa de una función por nombre exacto |
| Todas las funciones wrapper con resúmenes y etiquetas |
| Pide a Codex que implemente y registre un nuevo wrapper de datos |
search_tools
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 escribe findata/<module>.py, actualiza server.py y recarga en caliente la nueva función en el registro en vivo: no se necesita reiniciar.
Variables de entorno
Variable | Description |
| Autenticación de Codex: omite OAuth si está configurado (alternativa al montaje de autenticación del host) |
| Requerido para |
| Sobrescribe la ruta del binario de Codex (por defecto |
| Host de la API de Bloomberg para las funciones |
| Puerto de la API de Bloomberg (por defecto |
| Espera por evento antes de abandonar una solicitud de Bloomberg (por defecto |
| Cadena |
Referencia rápida de 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, RFget_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, volumeget_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 tickersget_bloomberg_ticks — datos a nivel de tick para cualquier valor
Requiere una Terminal de Bloomberg, derecho de SAPI o B-PIPE y el 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()La cadena de valor se pasa a Bloomberg tal cual, por lo que cualquier cosa que cotice la Terminal funciona: "AAPL US Equity", "ESZ5 Index", "EURUSD Curncy", "TY1 Comdty", "US912810TW33 Govt".
Las ventanas largas se dividen en sub-solicitudes de tamaño chunk (por defecto un día) y se concatenan, porque Bloomberg trunca silenciosamente una respuesta intradía demasiado grande en lugar de dar error. Los límites propios de Bloomberg siguen aplicándose: el historial de ticks intradía llega aproximadamente 140 días atrás, y los límites de volumen diario están vinculados a tu derecho.
Reutiliza una sesión al iterar sobre un universo: evita un apretón de manos de conexión por nombre:
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
}Agrega ticks en barras localmente, en cualquier offset de pandas:
from findata.bloomberg import ticks_to_bars
bars = ticks_to_bars(ticks, rule="5min")
# columns: open, high, low, close, ticks, volume, vwapget_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, valueget_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")Pruebas
pytest tests/ -vTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for Financial Modeling Prep API with 250+ financial data tools
Official Intrinio MCP server. US stock prices, options and fundamentals for AI agents.
One API and MCP server for financial and economic data: markets, economics, companies and more.
MCP server for stocksense-ai documentation, generated by doc2mcp.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA 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
- AlicenseAqualityDmaintenanceFinData 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.539 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that provides AI agents with financial tools including real-time quotes, backtesting, technical analysis, and multi-exchange data via a simple CLI interface.2MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to query real-time financial data including stock quotes, market indices, company fundamentals, and portfolio tracking.MIT