Yahoo Finance

Servidor MCP de Yahoo Finance

Un servidor de Protocolo de Contexto de Modelo (MCP) que brinda a los asistentes de IA acceso a datos de Yahoo Finance mediante yfinance. Consulte información de acciones, noticias financieras, rankings sectoriales y genere gráficos financieros profesionales, todo desde su chat de IA.

Características

• Datos de acciones — Información de la empresa, finanzas, métricas de valoración, dividendos y datos de negociación
• Datos de analistas — Objetivos de consenso, tendencias de estimaciones/revisiones, historial de recomendaciones y acciones a nivel de firma
• Estados financieros — Estado de resultados y balance general con datos históricos (EBIT, capital invertido, etc.)
• Noticias financieras — Artículos de noticias recientes y comunicados de prensa para cualquier ticker
• Búsqueda — Encuentre acciones, ETF y noticias en Yahoo Finance
• Rankings sectoriales — Principales ETF, fondos mutuos, empresas, líderes de crecimiento y mejores rendimientos por sector
• Historial de precios — Datos OHLCV históricos como tablas Markdown o gráficos profesionales
• Generación de gráficos — Gráficos de velas, VWAP y perfil de volumen devueltos como imágenes WebP
• Datos de opciones — Cadenas de opciones con calls, puts, precios de ejercicio, IV y fechas de vencimiento
• Datos de propiedad — Principales tenedores, inversores institucionales, tenedores de fondos mutuos y transacciones de información privilegiada
• Transparencia de fondos — Tenencias de ETF y fondos mutuos, clases de activos, sectores, calificaciones y detalles operativos
• Filtros — Árboles de consulta predefinidos, de acciones, de fondos mutuos y de ETF

Herramientas

yfinance_get_ticker_info

Recupere datos completos de acciones, incluida información de la empresa, finanzas, métricas de negociación y datos de gobernanza.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción (p. ej., AAPL, GOOGL, MSFT)

Devuelve: Objeto JSON con detalles de la empresa, datos de precios, métricas de valoración, información de negociación, dividendos, finanzas e indicadores de rendimiento.

yfinance_get_analyst_price_targets

Obtenga el precio actual y los objetivos de precio de consenso de los analistas para una acción.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción (p. ej., AAPL, GOOGL, MSFT)

Devuelve: Objeto JSON con los campos de precio current, low, high, mean y median. La cobertura de analistas y los campos disponibles varían según el símbolo.

yfinance_get_analyst_estimates

Obtenga estimaciones de consenso de analistas, impulso de revisiones, recomendaciones, estimaciones de crecimiento e historial de ganancias.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción
sections	array	No	Cualquiera de recommendations, earnings_estimate, revenue_estimate, eps_trend, eps_revisions, earnings_history o growth_estimates. Omita para todas las secciones
max_rows	number	No	Máximo de filas por sección. Predeterminado: 12. Use 0 para todas las filas

Devuelve: Matrices con nombre para las secciones disponibles, además de _metadata que contiene recuentos de filas por sección, estado de truncamiento, secciones no disponibles y secciones fallidas. Una falla en una sección no descarta las secciones obtenidas correctamente.

yfinance_get_upgrades_downgrades

Obtenga mejoras, rebajas, iniciaciones, reiteraciones y cambios de objetivo de precio de analistas, de más reciente a más antiguo.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción
max_rows	number	No	Máximo de acciones a devolver. Predeterminado: 25. Use 0 para devolver todas las filas

Devuelve: Objeto JSON que contiene registros de upgrades_downgrades y _metadata con recuentos de filas y estado de truncamiento. Los registros pueden incluir:

• GradeDate: Fecha y hora de la acción del analista
• Firm: Nombre de la firma de analistas
• ToGrade y FromGrade: Calificaciones nueva y anterior
• Action: Acción de calificación
• priceTargetAction: Acción sobre el objetivo de precio, como Raises, Lowers o Maintains
• currentPriceTarget y priorPriceTarget: Objetivos de precio nuevo y anterior

Los campos disponibles varían según el símbolo y la acción del analista.

yfinance_get_ticker_news

Obtenga artículos de noticias recientes y comunicados de prensa para una acción específica.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción

Devuelve: Matriz JSON de elementos de noticias con título, resumen, fecha de publicación, proveedor, URL y miniatura.

yfinance_search

Busque en Yahoo Finance acciones, ETF y artículos de noticias.

Parámetro	Tipo	Obligatorio	Descripción
query	string	Sí	Consulta de búsqueda: nombre de la empresa, símbolo del ticker o palabras clave
search_type	string	Sí	"all" (cotizaciones + noticias), "quotes" (solo acciones/ETF) o "news" (solo artículos)

Devuelve: Cotizaciones y/o resultados de noticias coincidentes según search_type.

yfinance_get_top

Obtenga las entidades financieras mejor clasificadas dentro de un sector de mercado.

Parámetro	Tipo	Obligatorio	Descripción
sector	string	Sí	Sector de mercado (consulte sectores admitidos a continuación)
top_type	string	Sí	"top_etfs", "top_mutual_funds", "top_companies", "top_growth_companies" o "top_performing_companies"
top_n	number	No	Número de resultados a devolver (predeterminado: 10, máximo: 100)

Devuelve: Matriz JSON de entidades principales con métricas relevantes.

Sectores admitidos

Basic Materials, Communication Services, Consumer Cyclical, Consumer Defensive, Energy, Financial Services, Healthcare, Industrials, Real Estate, Technology, Utilities

yfinance_screen

Ejecute filtros de Yahoo Finance utilizando claves de filtro predefinidas o árboles de consulta personalizados.

Parámetro	Tipo	Obligatorio	Descripción
query	string/object	Sí	Para query_type="predefined": clave de filtro como "day_gainers". Para query_type="equity", "fund" o "etf": árbol de consulta personalizado con nodos {operator, operands}
query_type	string	No	"predefined" (predeterminado), "equity", "fund" o "etf"
offset	number	No	Desplazamiento de resultados
size	number	No	Filas para consultas personalizadas; el máximo de Yahoo es 250
count	number	No	Filas para consultas predefinidas; el máximo de Yahoo es 250
sort_field	string	No	Campo de ordenación, por ejemplo "percentchange"
sort_asc	boolean	No	Orden ascendente si true, descendente si false
user_id	string	No	Identificador de usuario de Yahoo opcional
user_id_type	string	No	Tipo de ID de usuario de Yahoo opcional, comúnmente "guid"

Devuelve: Respuesta JSON del filtro de Yahoo Finance, que generalmente incluye filas de cotizaciones y metadatos.

Ejemplo de filtro de acciones personalizado:

{
  "query_type": "equity",
  "query": {
    "operator": "and",
    "operands": [
      { "operator": "gt", "operands": ["percentchange", 3] },
      { "operator": "eq", "operands": ["region", "us"] },
      { "operator": "gte", "operands": ["intradayprice", 5] },
      { "operator": "gt", "operands": ["dayvolume", 500000] }
    ]
  },
  "sort_field": "percentchange",
  "sort_asc": false,
  "size": 50
}

Ejemplo de filtro de ETF personalizado:

{
  "query_type": "etf",
  "query": {
    "operator": "and",
    "operands": [
      { "operator": "eq", "operands": ["categoryname", "Large Blend"] },
      { "operator": "lte", "operands": ["annualreportnetexpenseratio", 0.2] }
    ]
  },
  "sort_field": "fundnetassets",
  "sort_asc": false,
  "size": 25
}

yfinance_screen_gappers

Ejecute un filtro personalizado diseñado específicamente para detectar gaps alcistas en la sesión de apertura.

Parámetro	Tipo	Obligatorio	Descripción
min_percent_change	number	No	Porcentaje/cambio mínimo de gap respecto al cierre anterior (predeterminado: 3.0)
min_price	number	No	Precio intradía mínimo (predeterminado: 5.0)
min_volume	number	No	Volumen diario mínimo (predeterminado: 500000)
min_market_cap	number	No	Capitalización de mercado intradía mínima en USD (predeterminado: 2000000000)
region	string	No	Código de región de Yahoo (predeterminado: "us")
size	number	No	Número de resultados (predeterminado: 50, máximo: 250)
offset	number	No	Desplazamiento de resultados para paginación (predeterminado: 0)
sort_asc	boolean	No	Ordenar por percentchange ascendente (true) o descendente (false, predeterminado)

Devuelve: Respuesta JSON del filtro de Yahoo Finance.

yfinance_get_price_history

Obtenga datos históricos de precios y, opcionalmente, genere gráficos de análisis técnico.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción
period	string	No	Rango de tiempo: 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max (predeterminado: 1mo)
interval	string	No	Granularidad de datos: 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo (predeterminado: 1d)
chart_type	string	No	Gráfico a generar (omita para datos tabulares)
prepost	boolean	No	Incluir datos previos y posteriores a la apertura del mercado cuando estén disponibles (predeterminado: false; útil con solicitudes intradía como period="1d", interval="1m")

Tipos de gráficos:

Valor	Descripción
"price_volume"	Gráfico de velas con barras de volumen
"vwap"	Gráfico de precios con superposición de Precio Promedio Ponderado por Volumen
"volume_profile"	Gráfico de velas con distribución de volumen por nivel de precio

Devuelve:

• Sin chart_type: Tabla Markdown con columnas de Fecha, Apertura, Máximo, Mínimo, Cierre, Volumen, Dividendos y Divisiones de acciones.
• Con chart_type: Imagen WebP codificada en Base64 para un uso eficiente de tokens.

yfinance_get_financials

Obtenga estados financieros (estado de resultados, balance general y flujo de caja) con datos históricos.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción
frequency	string	No	"annual" (anual), "quarterly" (trimestral) o "ttm" (últimos doce meses). Predeterminado: "annual"

Devuelve: Objeto JSON con datos de estado de resultados, balance general y flujo de caja para cada período de reporte.

• Campos del estado de resultados: EBIT, Ingreso neto, Provisión de impuestos, Ingreso antes de impuestos, Gasto por intereses, Ingresos totales, Ingreso operativo, EBITDA, Ingreso normalizado
• Campos del balance general: Patrimonio de los accionistas, Deuda total, Efectivo y equivalentes de efectivo, Capital invertido, Deuda neta, Activos totales, Pasivos totales netos de interés minoritario, Activos tangibles netos, Valor contable tangible
• Campos del flujo de caja: Flujo de caja operativo, Flujo de caja libre, Gasto de capital, Ingreso neto de operaciones continuadas, Depreciación y amortización, Cambio en capital de trabajo, Dividendos en efectivo pagados

yfinance_get_holders

Obtenga principales tenedores, tenedores institucionales, tenedores de fondos mutuos y datos de información privilegiada.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción (p. ej., AAPL, MSFT)
max_rows	number	No	Máximo de filas devueltas por sección de tenedores. Predeterminado: 10. Use 0 para devolver todas las filas
Devuelve: Objeto JSON con:

• major_holders — Desglose agregado donde cada fila tiene una etiqueta index (p. ej. insidersPercentHeld, institutionsPercentHeld, institutionsFloatPercentHeld, institutionsCount) y un Value
• institutional_holders — Inversores institucionales; los registros suelen incluir campos como Date Reported, Holder, Shares, Value, pctChange, pctHeld
• mutualfund_holders — Tenedores de fondos mutuos; los registros suelen incluir campos similares a los de los tenedores institucionales
• insider_transactions — Operaciones recientes de información privilegiada; los registros suelen incluir campos como Shares, Value, Insider, Position, Transaction, Start Date, Ownership
• insider_purchases — Resumen de seis meses donde cada fila describe una categoría (Compras, Ventas, Acciones netas, etc.); los registros suelen incluir campos como Insider Purchases Last 6m, Shares, Trans
• insider_roster — Iniciados conocidos; los registros suelen incluir campos como Name, Position, Shares Owned Directly, Most Recent Transaction, Latest Transaction Date
• _metadata — Metadatos de límite de filas con max_rows y por sección total_rows, returned_rows y truncated

Las secciones de tenedores están limitadas a 10 filas por defecto para mantener las respuestas concisas. Pase max_rows: 0 cuando necesite los conjuntos de datos completos de tenedores. Los nombres de campos para los conjuntos de datos relacionados con tenedores los proporciona yfinance y pueden variar según el ticker, la disponibilidad de datos y la versión de yfinance.

yfinance_get_fund_data

Obtenga la composición de la cartera y los detalles operativos de un ETF o fondo mutuo.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker del ETF o fondo mutuo (por ejemplo SPY, BND o VFIAX)
sections	array	No	Cualquiera de description, fund_overview, fund_operations, asset_classes, top_holdings, equity_holdings, bond_holdings, bond_ratings o sector_weightings. Omita para todas las secciones
max_rows	number	No	Máximo de filas por sección tabular. Predeterminado: 25. Use 0 para todas las filas

Devuelve: Secciones de fondos disponibles más _metadata con límites de filas, truncamiento por sección, secciones no disponibles y secciones fallidas. La combinación de secciones depende del fondo; por ejemplo, los fondos de acciones y los fondos de bonos exponen diferentes desgloses de cartera.

yfinance_get_option_dates

Obtenga las fechas de vencimiento de opciones disponibles para una acción.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción (p. ej. AAPL, MSFT)

Devuelve: Matriz JSON de fechas de vencimiento en formato AAAA-MM-DD.

yfinance_get_option_chain

Obtenga los datos de la cadena de opciones (calls y puts) para una acción con precios de ejercicio disponibles.

Parámetro	Tipo	Obligatorio	Descripción
symbol	string	Sí	Símbolo del ticker de la acción
expiration_date	string	No	Fecha de vencimiento de la opción en formato AAAA-MM-DD. Omita para obtener todas las fechas.
option_type	string	No	"calls", "puts" o "all" (predeterminado: "all")

Devuelve: Objeto JSON claveado por fecha de vencimiento, con datos de calls y/o puts que incluyen:

• contractSymbol: Identificador del contrato de opción
• strike: Precio de ejercicio
• lastPrice: Último precio negociado
• bid/ask: Precios de oferta y demanda
• volume: Volumen de negociación
• openInterest: Interés abierto
• impliedVolatility: IV
• inTheMoney: Si la opción está ITM
• contractSize: Tamaño del contrato (REGULAR)
• currency: Moneda (USD)

Uso

Mediante uv (recomendado)

1. Instale uv
2. Agregue lo siguiente a la configuración de su cliente MCP:

{
  "mcpServers": {
    "yfmcp": {
      "command": "uvx",
      "args": ["yfmcp@latest"]
    }
  }
}

Mediante Docker

{
  "mcpServers": {
    "yfmcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "narumi/yfinance-mcp"]
    }
  }
}

Desde el código fuente

1. Clone el repositorio e instale las dependencias:

git clone https://github.com/narumiruna/yfinance-mcp.git
cd yfinance-mcp
uv sync

2. Agregue lo siguiente a la configuración de su cliente MCP:

{
  "mcpServers": {
    "yfmcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/yfinance-mcp",
        "yfmcp"
      ]
    }
  }
}

Reemplace /path/to/yfinance-mcp con la ruta real a su repositorio clonado.

Pruebas con Codex CLI

Este repositorio incluye .codex/config.toml, que registra el servidor MCP local yfmcp para Codex CLI usando uv run yfmcp. Después de clonar el repositorio y ejecutar uv sync, abra Codex CLI desde la raíz del repositorio y pruebe indicaciones como:

Show VOO ticker info
Show VOO price history for the last 5 days
Find the ticker symbol for Toyota
Get AAPL option expiration dates

Desarrollo

Requisitos previos

• Python ≥ 3.12
• Administrador de paquetes uv

Configuración

uv sync --extra dev

Lint y formato

uv run ruff check .
uv run ruff format .

Verificación de tipos

uv run ty check src tests

Prueba

uv run pytest -v -s --cov=src tests

Chatbot de demostración

Consulte el chatbot de demostración en su repositorio dedicado: yfinance-mcp-demo

Contribuyentes

Hecho con contrib.rocks.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.