FinanceMCP

[!WARNING] Estado del servicio: el servicio de alojamiento público está temporalmente suspendido. El dominio público original ha expirado; actualmente no se ofrece experiencia en línea oficial ni endpoint /mcp alojado. El dominio puede cambiar en el futuro; el tiempo de restauración y la nueva dirección se anunciarán en este repositorio. El paquete npm, el uso local de stdio y el despliegue propio no se ven afectados.

[!IMPORTANT] v4.11.2 refuerza la validación de parámetros, los límites de tamaño de solicitud, la fallback de fuentes de datos y el esquema dinámico de herramientas para el enrutamiento de noticias de Twingly, y añade enmascaramiento de encabezados de solicitud sensibles. Los nombres de las 19 herramientas existentes y los principales métodos de llamada permanecen sin cambios.

[!NOTE] Cuando necesites compartir el enrutamiento de prompts/KV-cache del modelo y el linaje de conversación entre Trae, Cursor, Claude Code y Codex, puedes iniciar opcionalmente un finance-cache-gateway independiente. Utiliza un proceso, puerto y configuración separados; no modifica las herramientas MCP existentes, stdio ni la interfaz /mcp, y el uso actual permanece completamente sin cambios si no se activa.

🔗 Proyecto vinculado: Sistema de documentos financieros inteligentes FinNote

FinanceMCP se ha vinculado e integrado con MarkiNote para formar un sistema integrado FinNote orientado a escenarios de investigación financiera, análisis de IA y gestión de documentos inteligentes. Este proyecto participó en el Concurso de Capacidad de Aplicación Informática para Estudiantes Universitarios de Shanghái y obtuvo el segundo premio.

🌐 Experiencia en línea: temporalmente suspendida, el dominio puede cambiar en el futuro 📝 MarkiNote: https://github.com/wink-wink-wink555/MarkiNote

En la arquitectura general de FinNote, FinanceMCP actúa como la capa de servicios de datos financieros y herramientas MCP central, construida sobre Node.js, Express y el SDK de Model Context Protocol (MCP). Actualmente, a través de 19 herramientas MCP estables, proporciona a los agentes de IA capacidades de datos financieros como acciones, fondos, bonos, macroeconomía, noticias financieras, indicadores técnicos y cotizaciones de múltiples mercados, y admite dos métodos de integración: stdio y Streamable HTTP.

MarkiNote, por su parte, actúa como el sistema de gestión de documentos y conocimiento inteligente para agentes de IA de nivel superior, encargado de albergar la interacción en lenguaje natural, la visualización de resultados de análisis de IA, la generación de documentos Markdown, la edición y la acumulación de conocimiento a largo plazo. En el escenario FinNote, MarkiNote llama a FinanceMCP a través de la cadena de servicios HTTP / MCP, permitiendo que las capacidades de datos financieros entren directamente en el flujo de trabajo de razonamiento y documentos del agente de IA.

El flujo general forma:

Pregunta en lenguaje natural → Comprensión de tareas del agente de IA → Llamada a herramientas FinanceMCP → Obtención de datos financieros de múltiples fuentes → Análisis inteligente de IA → Generación de documentos Markdown → Gestión de documentos y acumulación de conocimiento

Por lo tanto, FinanceMCP no solo puede integrarse como un servidor MCP de datos financieros independiente en clientes MCP o agentes de IA como Claude, Cursor, Codex, sino que también puede servir como infraestructura de datos financieros para aplicaciones de IA de nivel superior como FinNote, proporcionando capacidades de datos unificadas, estructuradas, invocables y trazables para investigación de inversiones inteligente, análisis financiero y agentes basados en documentos.

✨ Características principales

	Capacidad	Descripción
🔌	Extensión no intrusiva	Mantiene los nombres y parámetros de las 19 herramientas existentes; la selección de fuentes de datos se realiza mediante el contexto de la solicitud
🧭	Enrutamiento inteligente	Admite simultáneamente Tushare, Qveris, Binance y fuentes de noticias públicas
🔁	Degradación automática	Si la fuente preferida no cubre, supera el tiempo de espera, está limitada o no está disponible, continúa intentando según la prioridad
🏷️	Transparencia de fuentes	Cada respuesta indica la fuente de datos real; cuando ocurre una degradación, también devuelve la ruta completa
🛡️	Aislamiento a nivel de solicitud	La clave HTTP se aísla mediante AsyncLocalStorage, y los registros se enmascaran uniformemente
📈	Cobertura de múltiples mercados	Acciones A, acciones de Hong Kong, acciones de EE. UU., índices, fondos, bonos, futuros, divisas, macroeconomía y activos criptográficos
🧮	Motor de indicadores técnicos	MACD, RSI, KDJ, BOLL, MA expanden automáticamente la ventana histórica antes de calcular
🚀	Modo de doble transporte	Admite simultáneamente stdio local y Streamable HTTP remoto

🧭 Enrutamiento de fuentes de datos

flowchart LR
    C[AI / MCP Client] -->|现有 19 个 Tools| R{FinanceMCP Router}
    R -->|默认优先| T[Tushare]
    R -->|全球新闻| G[Twingly]
    R -->|可选扩展| Q[Qveris]
    R -->|Crypto| B[Binance]
    R -->|News / Time| L[公开源与本地计算]
    Q -. 未覆盖 / 超时 / 限流 .-> T
    T -. 不适用 .-> B
    T & G & Q & B & L --> O[来源标注后的统一 MCP 结果]

Encabezados de solicitud HTTP

X-Tushare-Token: YOUR_TUSHARE_TOKEN
X-Qveris-Api-Key: YOUR_QVERIS_API_KEY
X-Twingly-Api-Key: YOUR_TWINGLY_API_KEY
X-Finance-Source-Priority: twingly,qveris,tushare,binance

Prioridad predeterminada:

tushare,twingly,qveris,binance

Comportamiento de enrutamiento:

1. Si solo se pasa una credencial, se prioriza la fuente de datos correspondiente a esa credencial.
2. Si se pasan múltiples credenciales, Tushare tiene prioridad por defecto; las herramientas de noticias intentan Twingly primero, luego Qveris y fuentes públicas.
3. X-Finance-Source-Priority puede ajustar el orden por solicitud; los elementos desconocidos se ignoran, los duplicados se eliminan y los faltantes se completan según el orden predeterminado.
4. Si la interfaz de la fuente preferida no cubre o falla, se degrada automáticamente; los resultados vacíos normales no activan solicitudes repetidas.
5. Qveris ejecuta internamente Discover → Inspect → Probe → Call, y cada solicitud MCP ejecuta como máximo una llamada potencialmente facturable.

Ejemplo de respuesta:

数据来源: Tushare
数据源路由: Qveris（接口未覆盖） → Tushare（成功）

原有工具结果……

[!NOTE] Qveris es una extensión opcional. Si no se proporcionan X-Qveris-Api-Key / QVERIS_API_KEY, no se llamará a Qveris ni se consumirán créditos. El contrato de la interfaz se encuentra en Qveris REST API.

[!NOTE] Twingly es una fuente de noticias global opcional. Si no se proporcionan X-Twingly-Api-Key / TWINGLY_API_KEY, no se llamará. FinanceMCP solo devuelve títulos, fuentes, fechas, identificadores de artículos y sitios, URL, idioma/región, secciones y metadatos de deduplicación; no devuelve ni persiste el texto completo de los artículos.

Visualización dinámica de herramientas según credenciales

tools/list recorta el catálogo de herramientas según las credenciales realmente transportadas en la solicitud MCP actual: si solo se pasa la clave de Twingly, se muestran las dos herramientas de noticias existentes; si solo se pasa la clave de Qveris, solo se muestran las herramientas existentes cubiertas por el adaptador de Qveris; si solo se pasa el token de Tushare, solo se muestran las herramientas cubiertas por Tushare; si se pasan múltiples credenciales, se muestra la unión. Sin credenciales, solo se muestran fuentes de datos públicas y herramientas locales. tools/call también realiza la misma validación para evitar que la IA llame a fuentes de datos no disponibles para la solicitud actual.

🔑 Fuentes de datos y obtención de API

Fuente de datos	¿Requiere credencial?	Entrada oficial de obtención	Configuración de FinanceMCP
Tushare Pro	Requiere Token	Registrar cuenta · Obtener Token	stdio: TUSHARE_TOKEN; HTTP: X-Tushare-Token
Qveris	Requiere API Key	Dashboard / API Keys · Documentación oficial	stdio: QVERIS_API_KEY; HTTP: X-Qveris-Api-Key
Twingly News Search	Requiere API Key	Dashboard / API Key · News API	stdio: TWINGLY_API_KEY; HTTP: X-Twingly-Api-Key
Binance Public API	No requiere	Documentación de Spot REST API	Sin configuración; las cotizaciones de activos criptográficos usan automáticamente la interfaz pública
Baidu News	No requiere	Sin necesidad de solicitar API	Sin configuración; finance_news usa búsqueda pública de noticias
Reloj del sistema local	No requiere	Ninguno	Sin configuración; solo para uso de current_timestamp

Token de Tushare

1. Regístrate e inicia sesión en Tushare.
2. Ve a Centro personal → Cuenta y TOKEN, copia el Token; los pasos completos están en la Guía oficial de Token.
3. Escribe el Token en TUSHARE_TOKEN local, o pásalo a través de X-Tushare-Token en solicitudes MCP remotas.

[!TIP] 🎓 La verificación de estudiantes universitarios de Tushare puede obtener 2000 puntos gratis. El proceso oficial actual requiere completar la información de la escuela y personal, unirse al grupo de usuarios universitarios y enviar al administrador una captura de pantalla del carnet de estudiante o de la plataforma de verificación académica (Xuexin) junto con el ID de Tushare. La entrada y los pasos más recientes están en Obtención de puntos gratuitos para estudiantes. El acuerdo de servicio de Tushare también indica que los estudiantes universitarios y profesores, tras confirmar su identidad, pueden obtener 2000 / 5000 puntos respectivamente. Los umbrales de puntos y frecuencias varían según la interfaz; consulta la documentación de la interfaz correspondiente y la página de permisos de puntos.

API Key de Qveris

1. Inicia sesión en Qveris, abre Dashboard / API Keys.
2. Crea y copia la API Key. Qveris actualmente ofrece 1000 créditos para cuentas nuevas; Discover e Inspect son gratuitos, y las llamadas reales pueden facturarse según la capacidad.
3. Escribe la Key en QVERIS_API_KEY local, o pásala a través de un X-Qveris-Api-Key independiente en solicitudes MCP remotas.

API Key de Twingly

1. Inicia sesión en Twingly Dashboard, copia la API Key desde la esquina superior derecha y confirma el saldo restante.
2. Escribe la Key en TWINGLY_API_KEY local, o pásala a través de un X-Twingly-Api-Key independiente en solicitudes MCP remotas.
3. Twingly solo actúa como proveedor opcional para finance_news y hot_news_7x24; si falla la autenticación, hay limitación de velocidad, error de servicio o no hay resultados coincidentes, se degrada automáticamente según la configuración. Si falla la validación de parámetros del llamador, no se degrada a una fuente de noticias semánticamente diferente.
4. finance_news trata por defecto el contenido separado por espacios como múltiples términos obligatorios; para frases exactas usa comillas dobles, por ejemplo "Federal Reserve" inflation. Twingly acepta como máximo 250 términos combinados y el cuerpo de la solicitud tiene un máximo de 16 KiB (en bytes UTF-8); exceder cualquiera de estos límites genera un error claro antes de enviar la solicitud al proveedor.
5. Twingly devuelve como máximo 250 noticias por solicitud. tools/list establece el límite del esquema de hot_news_7x24.limit en 250 cuando Twingly es la fuente de noticias preferida actual; otras fuentes de datos pueden seguir publicando sus propios límites.

Fuentes de datos sin Key

• Binance: FinanceMCP actualmente solo llama a la interfaz pública de velas con tipo de seguridad NONE, sin necesidad de cuenta de Binance, API Key o permisos de trading.
• Baidu News: Usa búsqueda pública de noticias, sin necesidad de credenciales de desarrollador; si la red o la búsqueda del proveedor no están disponibles, puede intentar la capacidad de noticias de Qveris según la prioridad configurada.

[!WARNING] No escribas Tokens / API Keys reales en el README, ejemplos de configuración de MCP ni los envíes a Git. Se recomienda usar .env, variables de entorno del cliente o el Header de cada solicitud HTTP.

🚀 Inicio rápido

npm / stdio

npx -y finance-mcp

Configuración de clientes MCP locales como Claude Desktop, Cursor, etc.:

{
  "mcpServers": {
    "finance-mcp": {
      "command": "npx",
      "args": ["-y", "finance-mcp"],
      "env": {
        "TUSHARE_TOKEN": "YOUR_TUSHARE_TOKEN",
        "QVERIS_API_KEY": "YOUR_QVERIS_API_KEY",
        "TWINGLY_API_KEY": "YOUR_TWINGLY_API_KEY",
        "FINANCE_SOURCE_PRIORITY": "tushare,twingly,qveris,binance"
      }
    }
  }
}

Streamable HTTP

El endpoint de alojamiento público está actualmente suspendido. Antes de que se confirme el nuevo dominio, usa la configuración stdio local anterior o despliega tu propio servicio Streamable HTTP:

{
  "mcpServers": {
    "finance-mcp": {
      "type": "streamableHttp",
      "url": "https://your-finance-mcp.example/mcp",
      "timeout": 600,
      "headers": {
        "X-Tushare-Token": "YOUR_TUSHARE_TOKEN",
        "X-Qveris-Api-Key": "YOUR_QVERIS_API_KEY",
        "X-Twingly-Api-Key": "YOUR_TWINGLY_API_KEY",
        "X-Finance-Source-Priority": "twingly,qveris,tushare,binance"
      }
    }
  }
}

Las tres credenciales son opcionales; puedes pasar solo una. Authorization: Bearer ... y X-Api-Key siguen siendo compatibles como Token de Tushare; Qveris y Twingly usan sus propios Headers independientes.

Variables de entorno

Variable	Valor predeterminado	Descripción
TUSHARE_TOKEN	vacío	Credencial de Tushare
QVERIS_API_KEY	vacío	Credencial de Qveris
QVERIS_BASE_URL	https://qveris.ai/api/v1	Dirección de la API REST de Qveris
TWINGLY_API_KEY	vacío	Credencial de Twingly News Search
TWINGLY_BASE_URL	https://data.twingly.net/news/b/search/v1/search	Dirección de la API de Twingly News Search
FINANCE_SOURCE_PRIORITY	tushare,twingly,qveris,binance	Prioridad predeterminada de stdio o servidor
PORT	3000	Puerto del servicio HTTP
MCP_HTTP_HOST	127.0.0.1	Dirección de escucha HTTP; para despliegue en contenedores usa 0.0.0.0
MCP_ALLOWED_HOSTS	Lista blanca de direcciones de loopback	Lista blanca de nombres de host separados por comas (sin puerto); para despliegues no loopback se recomienda configurar explícitamente

Instancia remota propia (opcional)

Actualmente no se ofrece un Endpoint oficial en línea. Si necesitas una dirección /mcp independiente, el archivo Dockerfile en la raíz del repositorio se puede desplegar directamente: el comando de inicio es node build/httpServer.js, escucha en 0.0.0.0, lee PORT desde variables de entorno y proporciona GET /health. Si se habilita un nuevo dominio oficial en el futuro, se anunciará en este repositorio.

docs/deploy-dockhold.md usa Dockhold como ejemplo (solo una de las formas de alojamiento, no es una plataforma afiliada ni recomendada), explicando el endpoint HTTPS, la ubicación de TUSHARE_TOKEN y QVERIS_API_KEY, y por qué se recomienda encarecidamente configurar MCP_ALLOWED_HOSTS cuando es accesible públicamente.

🧰 19 herramientas MCP

Herramienta	Función	Fuente de datos / Proveedor
current_timestamp	Marca de tiempo actual UTC+8	Reloj del sistema local
finance_news	Búsqueda de noticias financieras por palabras clave	Twingly* · Baidu News · Qveris*
stock_data	Cotizaciones históricas e indicadores técnicos de múltiples mercados	Tushare Pro · Qveris* · Binance Public API (activos criptográficos)
stock_data_minutes	Velas de minutos para acciones A y activos criptográficos	Tushare Pro · Qveris* · Binance Public API (activos criptográficos)
index_data	Cotizaciones de índices, información básica y valoración	Tushare Pro · Qveris*
macro_econ	GDP, CPI, PPI, PMI, Shibor, LPR, Libor, Hibor, etc.	Tushare Pro · Qveris*
company_performance	Datos de empresas de acciones A, finanzas, dividendos, accionistas y valoración	Tushare Pro · Qveris*
company_performance_hk	Estado de resultados, balance y flujo de caja de acciones de Hong Kong	Tushare Pro · Qveris*
company_performance_us	Estados financieros e indicadores de acciones de EE. UU.	Tushare Pro · Qveris*
fund_data	Valor liquidativo de fondos, tenencias, dividendos e información básica	Tushare Pro
fund_manager_by_name	Consulta de gestores de fondos y fondos gestionados	Tushare Pro
convertible_bond	Datos del ciclo de vida completo de bonos convertibles	Tushare Pro
block_trade	Detalles de transacciones en bloque	Tushare Pro
money_flow	Flujos de capital de acciones individuales, mercado general, sectores y conectividad	Tushare Pro
margin_trade	Datos de financiamiento con margen y préstamo de valores	Tushare Pro
csi_index_constituents	Rendimiento de índices CSI, pesos de componentes y resumen financiero	Tushare Pro · Qveris*
dragon_tiger_inst	Detalles de transacciones institucionales en la lista de dragones y tigres	Tushare Pro
hot_news_7x24	Puntos calientes financieros 7×24 y deduplicación de contenido	Tushare Pro · Twingly* · Qveris*
futures_data	Ranking de posiciones de miembros de futuros	Tushare Pro

Qveris* es una capa de enrutamiento de capacidades de datos dinámicas que selecciona automáticamente el proveedor real conectado según la consulta (por ejemplo, Finnhub, Tiingo, etc.); el proveedor finalmente seleccionado, el ID de capacidad y la fuente de datos se devuelven junto con el resultado de la herramienta. Las herramientas sin marca Qveris devolverán explícitamente "interfaz no cubierta" y luego se degradarán a las fuentes de datos nativas de la tabla.

📊 Indicadores técnicos

macd(12,26,9)   rsi(14)   kdj(9,3,3)   boll(20,2)   ma(5) ma(10) ma(20)

stock_data obtiene automáticamente los datos históricos adicionales necesarios para los indicadores, y después de calcular, recorta al rango solicitado por el usuario. Las solicitudes con indicadores técnicos mantienen el uso de fuentes de datos nativas para garantizar la estabilidad de los formatos de cálculo y visualización existentes.

🛠️ Desarrollo local

git clone https://github.com/guangxiangdebizi/FinanceMCP.git
cd FinanceMCP
cp .env.example .env
npm ci
npm test

npm run start:stdio   # stdio
npm run start:http    # http://127.0.0.1:3000/mcp

node_modules/ y build/ son artefactos generados localmente y no se incluyen en el seguimiento de Git. La publicación de npm se construye automáticamente mediante prepare, empaquetando solo el build/ necesario para la ejecución.

🛡️ Diseño de seguridad

• Las API Keys solo se leen desde el Header de la solicitud o variables de entorno, nunca se escriben en el repositorio.
• Las credenciales de solicitudes HTTP se aíslan por solicitud; los Headers sensibles se muestran como [REDACTED] en los registros.
• QVERIS_BASE_URL fuerza HTTPS por defecto; solo las direcciones loopback permiten pruebas de regresión HTTP.
• Las capacidades candidatas de Qveris pasan por filtrado de solo lectura, Probe de parámetros, límites de tamaño de respuesta y control de tiempo de espera.
• .env, directorios de dependencias, artefactos de construcción, registros y materiales de investigación local están gestionados por reglas de Git ignore.

⭐ Tendencia de estrellas

Si FinanceMCP te resulta útil, te invitamos a dar una ⭐. El gráfico de tendencias se actualiza automáticamente cada lunes mediante las GitHub Actions del propio repositorio, y también admite actualización manual; usa el GITHUB_TOKEN temporal del repositorio, sin depender de servicios de terceros de recopilación de estrellas ni credenciales a largo plazo.

🤝 Ecosistema y contribuciones

• FinanceMCP puede usarse como backend de datos financieros para FinNote / MarkiNote.
• Experiencia en línea: el servicio de alojamiento público está temporalmente suspendido, el dominio puede cambiar en el futuro
• Directorios del ecosistema MCP: Glama · Smithery · MCP Toplist
• Tutorial en video: Guía completa de uso de FinanceMCP
• Bugs y sugerencias de funciones: GitHub Issues

Se aceptan Issues y Pull Requests. Al añadir nuevas capacidades de datos, prioriza la compatibilidad con las herramientas agregadas existentes, evitando la expansión superficial de una herramienta por interfaz.

📄 Licencia

MIT