MCP Yahoo Finance

MCP Yahoo Finance

Un servidor de Model Context Protocol (MCP) para Yahoo Finance. Proporciona herramientas para precios, información de empresas, datos históricos, estados financieros, noticias, recomendaciones, ganancias, dividendos y opciones.

mcp-yahoo-finance está en desarrollo temprano. Los nombres de las herramientas y los campos de respuesta pueden cambiar entre versiones.

Instalación

Puedes ejecutar mcp-yahoo-finance sin una instalación separada usando uvx.

Usando pip

Usando pip.

pip install mcp-yahoo-finance

Usando Git

También puedes instalar el paquete después de clonar el repositorio en tu máquina.

git clone git@github.com:maxscheijen/mcp-yahoo-finance.git
cd mcp-yahoo-finance
uv sync

Configuración

Claude Desktop

Agrega esto a tu claude_desktop_config.json:

{
    "mcpServers": {
        "yahoo-finance": {
            "command": "uvx",
            "args": ["mcp-yahoo-finance"]
        }
    }
}

También puedes usar docker:

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

VSCode

Agrega esto a tu .vscode/mcp.json:

{
    "servers": {
        "yahoo-finance": {
            "command": "uvx",
            "args": ["mcp-yahoo-finance"]
        }
    }
}

Ejemplos de preguntas

1. "¿Cuál es el precio de la acción de Apple?"
2. "Dame una cotización completa para AAPL con el cierre anterior, el rango intradía y el estado del mercado."
3. "Muéstrame la descripción general de la empresa para Nvidia."
4. "¿Cuál es la diferencia en el precio de las acciones entre Apple y Google?"
5. "¿Cuánto cambió el precio de la acción de Apple entre 2024-01-01 y 2025-01-01?"
6. "¿Cuáles son las fechas de vencimiento de opciones disponibles para AAPL?"
7. "Muéstrame la cadena de opciones para AAPL que vence el 2024-01-19"
8. "¿Cuáles son las opciones de compra y venta para Tesla?"

Formato de respuesta

Las llamadas a herramientas devuelven datos estructurados compatibles con JSON. Por ejemplo, una cotización completa se ve así:

{
  "symbol": "AAPL",
  "currentPrice": 243.5822,
  "previousClose": 241.33,
  "absoluteChange": 2.2522,
  "percentChange": 0.9331,
  "open": 242.1,
  "dayHigh": 244.2,
  "dayLow": 241.9,
  "volume": 45678901,
  "marketStatus": "REGULAR",
  "currency": "USD",
  "exchange": "NMS",
  "timestamp": "2025-01-02T15:30:00+00:00",
  "source": {
    "provider": "Yahoo Finance",
    "endpoint": "info",
    "fetchedAt": "2025-01-02T15:30:01+00:00"
  }
}

Los errores usan la misma forma para cada herramienta y se marcan como errores MCP:

{
  "error": {
    "code": "NO_DATA",
    "message": "No historical data found for AAPL"
  }
}

Los resultados históricos y tabulares mantienen sus nombres de columnas e incluyen fechas como cadenas de fecha de calendario YYYY-MM-DD. Esto es válido tanto para índices de Yahoo Finance ingenuos como conscientes de la zona horaria; la zona horaria del proveedor no se expone. Las herramientas de precios históricos, de fecha única y de rango de fechas devuelven precios ajustados por defecto (ajustes por división y dividendos). get_historical_stock_prices acepta adjusted: false cuando se requieren valores OHLC no ajustados. Una búsqueda de fecha única y un rango de fechas usan fechas de calendario inclusivas; los fines de semana y los días festivos del mercado devuelven un error estructurado NO_DATA cuando no existe una fila de negociación. Los campos faltantes de cotización y descripción general de la empresa se representan como null. Las noticias se limitan a 10 artículos por defecto (hasta 100), normalizan título, URL, editor, miniatura, símbolos relacionados y publishedAt como una marca de tiempo UTC ISO 8601, y aceptan filtros opcionales inclusivos start_date y end_date. Las recomendaciones, ganancias, dividendos, estados financieros y opciones usan el mismo campo de nivel superior symbol y devuelven datos con la forma del proveedor cuando están disponibles.

Herramientas disponibles

El servidor expone estas herramientas. Los valores symbol usan símbolos de ticker de Yahoo Finance, como AAPL o MSFT.

Herramienta	Propósito
get_current_stock_price	Precio actual y metadatos de cotización
get_rich_quote	Instantánea de cotización normalizada con precio, cambio, rango de sesión, estado del mercado y metadatos de fuente
get_company_overview	Perfil de empresa normalizado con sector, industria, capitalización de mercado, sitio web, número de empleados, descripción y metadatos de fuente
get_symbol_comparison	Comparación de cotización actual para hasta 20 símbolos
get_performance_analysis	Retornos multi-símbolo limitados, medias móviles, volatilidad, reducción, retorno relativo al índice de referencia y correlación
get_stock_price_by_date	Precio de cierre ajustado para una fecha de negociación
get_stock_price_date_range	Precios de cierre ajustados para un rango de fechas inclusivo
get_historical_stock_prices	Precios históricos por período e intervalo
get_dividends	Historial de dividendos
get_stock_splits	Historial de divisiones de acciones
get_capital_gains	Distribuciones de ganancias de capital
get_upcoming_dividends	Próximas fechas y tasas de dividendos
get_earnings_analytics	Sorpresas y estimaciones de ganancias
get_income_statement	Estado de resultados por frecuencia anual, trimestral o de arrastre
get_cashflow	Estado de flujo de efectivo por frecuencia
get_earning_dates	Fechas de ganancias recientes y próximas
get_news	Noticias de Yahoo Finance limitadas y normalizadas con filtros de fecha opcionales
get_recommendations	Recomendaciones de analistas
get_option_expiration_dates	Vencimientos de opciones disponibles
get_option_chain	Opciones de compra y venta limitadas para una fecha de vencimiento con filtros de precio de ejercicio, moneyness, liquidez, diferencial, tipo y recuento
get_option_summary	Volatilidad implícita, interés abierto, volumen, ratios put/call y resumen de máximo dolor para un vencimiento

El análisis de rendimiento utiliza cierres ajustados por división y dividendos. El retorno total es (last close / first close) - 1; la volatilidad anualizada es la desviación estándar de los retornos diarios multiplicada por sqrt(252); la reducción máxima es la reducción mínima desde un pico en curso. Las correlaciones usan retornos diarios en fechas de negociación compartidas, por lo que los símbolos con calendarios desiguales siguen siendo comparables.

Desarrollo local

Instala el entorno de desarrollo bloqueado con uv sync, luego ejecuta:

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build

El Makefile proporciona atajos para los comandos comunes:

make test
make lint
make docker-build

El conjunto de pruebas simula Yahoo Finance y no realiza solicitudes en vivo al proveedor.

Compilación

Compila la imagen de Docker con:

docker build -t mcp-yahoo-finance .

Prueba con MCP Inspector

npx @modelcontextprotocol/inspector uv run mcp-yahoo-finance

Limitaciones de Yahoo Finance

Los datos de Yahoo Finance son proporcionados por un tercero y pueden estar retrasados, incompletos o no disponibles. Este proyecto no proporciona asesoramiento de inversión y no garantiza la precisión, integridad u oportunidad de los datos devueltos. Verifica los valores importantes contra una fuente autorizada antes de confiar en ellos.