FinanceMCP

[!WARNING] Status do serviço: o serviço de hospedagem pública está temporariamente suspenso. O domínio público original expirou e atualmente não há experiência online oficial ou Endpoint /mcp hospedado; o domínio pode ser alterado no futuro, e o tempo de restauração e o novo endereço serão anunciados neste repositório. O pacote npm, o uso local via stdio e a implantação própria não são afetados.

[!IMPORTANT] v4.11.2 reforça a validação de parâmetros, limites de tamanho de solicitação, fallback de fontes de dados e Schema dinâmico de Tools na rota de notícias Twingly, além de adicionar mascaramento de cabeçalhos de solicitação sensíveis. Os nomes dos 19 Tools existentes e as principais formas de chamada permanecem inalterados.

[!NOTE] Quando for necessário compartilhar o roteamento de Prompt/KV-cache do modelo e o lineage de conversas entre Trae, Cursor, Claude Code e Codex, é possível iniciar opcionalmente um finance-cache-gateway independente. Ele usa processo, porta e configuração separados; não modifica os MCP Tools existentes, a interface stdio ou /mcp, e quando não está habilitado, o uso existente permanece completamente inalterado.

🔗 Integração de Projetos: FinNote — Sistema Inteligente de Documentos Financeiros

O FinanceMCP foi integrado e fundido com o MarkiNote, formando um sistema unificado FinNote voltado para pesquisa financeira, análise de IA e gerenciamento inteligente de documentos. O projeto participou da Competição de Capacidade de Aplicação de Computadores para Estudantes Universitários de Xangai e recebeu o segundo prêmio.

🌐 Experiência online: temporariamente suspensa, o domínio pode ser alterado no futuro 📝 MarkiNote：https://github.com/wink-wink-wink555/MarkiNote

Na arquitetura geral do FinNote, o FinanceMCP atua como a camada central de serviço de dados financeiros e ferramentas MCP, construída com Node.js, Express e o SDK do Model Context Protocol (MCP). Atualmente, por meio de 19 ferramentas MCP estáveis, fornece capacidades de dados financeiros para Agentes de IA, incluindo ações, fundos, títulos, macroeconomia, notícias financeiras, indicadores técnicos e cotações de múltiplos mercados, com suporte a duas formas de integração: stdio e Streamable HTTP.

O MarkiNote, por sua vez, atua como o sistema inteligente de documentos e gerenciamento de conhecimento para Agentes de IA, responsável por interação em linguagem natural, exibição de resultados de análise de IA, geração de documentos Markdown, edição e acúmulo de conhecimento de longo prazo. No cenário FinNote, o MarkiNote chama o FinanceMCP por meio da cadeia de serviços HTTP / MCP, permitindo que as capacidades de dados financeiros entrem diretamente no fluxo de raciocínio e trabalho documental do Agente de IA.

O fluxo geral forma:

Pergunta em linguagem natural → Compreensão da tarefa pelo Agente de IA → Chamada de ferramenta FinanceMCP → Obtenção de dados financeiros de múltiplas fontes → Análise inteligente de IA → Geração de documento Markdown → Gerenciamento de documentos e acúmulo de conhecimento

Portanto, o FinanceMCP pode ser usado não apenas como um MCP Server de dados financeiros independente, conectado a Clientes MCP ou Agentes de IA como Claude, Cursor, Codex, mas também como infraestrutura de dados financeiros para aplicações de IA de nível superior, como o FinNote, fornecendo capacidades de dados unificadas, estruturadas, chamáveis e rastreáveis para pesquisa de investimento inteligente, análise financeira e agentes baseados em documentos.

✨ Destaques Principais

	Capacidade	Descrição
🔌	Extensão não intrusiva	Mantém os nomes e parâmetros dos 19 Tools existentes; a seleção da fonte de dados é feita pelo contexto da solicitação
🧭	Roteamento inteligente	Suporta simultaneamente Tushare, Qveris, Binance e fontes de notícias públicas
🔁	Degradação automática	Se a fonte preferida não cobrir, expirar, sofrer rate limit ou ficar indisponível, continua tentando por prioridade
🏷️	Transparência da fonte	Cada retorno indica a fonte real dos dados; quando há degradação, retorna também a rota completa
🛡️	Isolamento por solicitação	A chave HTTP é isolada via AsyncLocalStorage, com logs mascarados de forma unificada
📈	Cobertura de múltiplos mercados	Ações A, Hong Kong, EUA, índices, fundos, títulos, futuros, câmbio, macroeconomia e ativos cripto
🧮	Motor de indicadores técnicos	MACD, RSI, KDJ, BOLL, MA com expansão automática da janela histórica antes do cálculo
🚀	Modo de transporte duplo	Suporta simultaneamente stdio local e Streamable HTTP remoto

🧭 Roteamento de Fontes de Dados

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 结果]

Cabeçalhos de Solicitação 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

Prioridade padrão:

tushare,twingly,qveris,binance

Comportamento de roteamento:

1. Ao enviar apenas uma credencial, a fonte de dados correspondente a essa credencial é usada preferencialmente.
2. Ao enviar múltiplas credenciais, o Tushare tem prioridade por padrão; as ferramentas de notícias tentam Twingly primeiro, depois Qveris e fontes públicas.
3. X-Finance-Source-Priority pode ajustar a ordem por solicitação; itens desconhecidos são ignorados, duplicados são removidos e itens ausentes são preenchidos na ordem padrão.
4. Se a interface da fonte preferida não cobrir ou falhar, há degradação automática; resultados vazios normais não acionam solicitações repetidas.
5. O Qveris executa internamente Discover → Inspect → Probe → Call, com no máximo uma chamada possivelmente cobrada por solicitação MCP.

Exemplo de retorno:

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

原有工具结果……

[!NOTE] O Qveris é uma extensão opcional. Sem X-Qveris-Api-Key / QVERIS_API_KEY, o Qveris não é chamado e não há consumo de créditos. O contrato da interface está em Qveris REST API.

[!NOTE] O Twingly é uma fonte de notícias global opcional. Sem X-Twingly-Api-Key / TWINGLY_API_KEY, ele não é chamado. O FinanceMCP retorna apenas título, fonte, data, identificadores de artigo e site, URL, idioma/região, seção e metadados de deduplicação; não retorna nem persiste o texto completo dos artigos.

Exibição dinâmica de Tools por credencial

tools/list filtra o catálogo de ferramentas com base nas credenciais realmente enviadas na solicitação MCP atual: apenas com a chave Twingly, exibe as duas ferramentas de notícias existentes; apenas com a chave Qveris, exibe apenas os Tools existentes cobertos pelo adaptador Qveris; apenas com o token Tushare, exibe apenas os Tools cobertos pelo Tushare; com múltiplas credenciais, exibe a união. tools/call também executa a mesma validação, evitando que a IA chame fontes de dados indisponíveis para a solicitação atual.

🔑 Fontes de Dados e Obtenção de API

Fonte de Dados	Requer credencial	Obtenção oficial	Configuração FinanceMCP
Tushare Pro	Requer Token	Registrar conta · Obter Token	stdio：TUSHARE_TOKEN；HTTP：X-Tushare-Token
Qveris	Requer API Key	Dashboard / API Keys · Documentação oficial	stdio：QVERIS_API_KEY；HTTP：X-Qveris-Api-Key
Twingly News Search	Requer API Key	Dashboard / API Key · News API	stdio：TWINGLY_API_KEY；HTTP：X-Twingly-Api-Key
Binance Public API	Não requer	Documentação da API REST Spot	Sem configuração; cotações de ativos cripto usam automaticamente a interface pública
Baidu News	Não requer	Sem necessidade de solicitar API	Sem configuração; finance_news usa busca pública de notícias
Relógio do sistema local	Não requer	Nenhum	Sem configuração; usado apenas por current_timestamp

Token Tushare

1. Registre-se e faça login no Tushare.
2. Acesse Central Pessoal → Conta e TOKEN, copie o Token; o passo a passo completo está no Guia oficial de Token.
3. Escreva o Token no TUSHARE_TOKEN local ou envie-o via X-Tushare-Token em solicitações MCP remotas.

[!TIP] 🎓 A certificação de estudante universitário no Tushare concede 2000 pontos gratuitamente. O processo oficial atual exige preencher dados da instituição e pessoais, entrar no grupo de usuários universitários e enviar ao administrador o comprovante de estudante ou captura de tela do Xuexin Wang, além do ID Tushare. A entrada e os passos mais recentes estão em Obtenção de pontos gratuitos para estudantes. O contrato de serviço do Tushare também informa que estudantes universitários e professores, após confirmação de identidade, recebem 2000 / 5000 pontos, respectivamente. Os limites de pontos e frequências variam por interface; consulte a documentação da interface correspondente e a página de permissões por pontos.

API Key Qveris

1. Faça login no Qveris e abra Dashboard / API Keys.
2. Crie e copie a API Key. O Qveris oferece atualmente 1000 créditos para novas contas; Discover e Inspect são gratuitos, e chamadas reais podem ser cobradas conforme a capacidade.
3. Escreva a Key no QVERIS_API_KEY local ou envie-a via X-Qveris-Api-Key independente em solicitações MCP remotas.

API Key Twingly

1. Faça login no Twingly Dashboard, copie a API Key no canto superior direito e confirme o saldo restante.
2. Escreva a Key no TWINGLY_API_KEY local ou envie-a via X-Twingly-Api-Key independente em solicitações MCP remotas.
3. O Twingly é apenas um upstream opcional para finance_news e hot_news_7x24; em caso de falha de autenticação, rate limit, erro de serviço ou nenhum resultado correspondente, há fallback automático conforme a configuração. Falha na validação de parâmetros do chamador não aciona fallback para uma fonte de notícias semanticamente diferente.
4. finance_news trata por padrão o conteúdo separado por espaços como múltiplos termos obrigatórios; para frases exatas, use aspas duplas, por exemplo "Federal Reserve" inflation. O Twingly aceita no máximo 250 termos combinados e o corpo da solicitação tem limite de 16 KiB (em bytes UTF-8); exceder qualquer um desses limites gera erro claro antes do envio ao upstream.
5. O Twingly retorna no máximo 250 notícias por vez. tools/list define o limite do schema de hot_news_7x24.limit como 250 quando o Twingly é a fonte de notícias preferida atual; outras fontes podem continuar divulgando seus próprios limites.

Fontes de dados sem Key

• Binance: o FinanceMCP atualmente chama apenas a interface pública de K-lines com tipo de segurança NONE, sem necessidade de conta Binance, API Key ou permissão de negociação.
• Baidu News: usa busca pública de notícias, sem necessidade de credenciais de desenvolvedor; se a rede ou a busca upstream estiver indisponível, tenta a capacidade de notícias do Qveris conforme a prioridade configurada.

[!WARNING] Não escreva Token / API Key reais no README, em exemplos de configuração MCP ou no Git. Recomenda-se usar .env, variáveis de ambiente do cliente ou o Header de cada solicitação HTTP.

🚀 Início Rápido

npm / stdio

npx -y finance-mcp

Configuração para clientes MCP locais 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

O Endpoint de hospedagem pública está temporariamente suspenso. Antes da confirmação do novo domínio, use a configuração stdio local acima ou implante seu próprio serviço 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"
      }
    }
  }
}

As três credenciais são opcionais; você pode enviar apenas uma delas. Authorization: Bearer ... e X-Api-Key continuam compatíveis como Token Tushare; Qveris e Twingly usam seus próprios Headers independentes.

Variáveis de ambiente

Variável	Padrão	Descrição
TUSHARE_TOKEN	vazio	Credencial Tushare
QVERIS_API_KEY	vazio	Credencial Qveris
QVERIS_BASE_URL	https://qveris.ai/api/v1	Endereço da API REST Qveris
TWINGLY_API_KEY	vazio	Credencial Twingly News Search
TWINGLY_BASE_URL	https://data.twingly.net/news/b/search/v1/search	Endereço da API Twingly News Search
FINANCE_SOURCE_PRIORITY	tushare,twingly,qveris,binance	Prioridade padrão para stdio ou servidor
PORT	3000	Porta do serviço HTTP
MCP_HTTP_HOST	127.0.0.1	Endereço de escuta HTTP; para implantação em contêiner, use 0.0.0.0
MCP_ALLOWED_HOSTS	whitelist de endereços loopback	Whitelist de nomes de host separados por vírgula (sem porta); para implantações não loopback, recomenda-se configurar explicitamente

Instância remota própria (opcional)

Atualmente não há Endpoint online oficial. Se você precisar de um endereço /mcp independente, o Dockerfile na raiz do repositório pode ser implantado diretamente: o comando de inicialização é node build/httpServer.js, escuta em 0.0.0.0, lê PORT de variáveis de ambiente e fornece GET /health. Se um novo domínio oficial for habilitado no futuro, será anunciado neste repositório.

docs/deploy-dockhold.md usa o Dockhold como exemplo (apenas uma forma de hospedagem, não é uma plataforma afiliada ou recomendada), explicando o endpoint HTTPS, a localização de TUSHARE_TOKEN e QVERIS_API_KEY, e por que é fortemente recomendado definir MCP_ALLOWED_HOSTS quando o serviço estiver acessível publicamente.

🧰 19 MCP Tools

Tool	Função	Fonte de dados / Provedor
current_timestamp	Carimbo de data/hora atual UTC+8	Relógio do sistema local
finance_news	Busca de notícias financeiras por palavra-chave	Twingly* · Baidu News · Qveris*
stock_data	Cotações históricas e indicadores técnicos de múltiplos mercados	Tushare Pro · Qveris* · Binance Public API (ativos cripto)
stock_data_minutes	K-lines de minutos para ações A e ativos cripto	Tushare Pro · Qveris* · Binance Public API (ativos cripto)
index_data	Cotações de índices, informações básicas e valuation	Tushare Pro · Qveris*
macro_econ	GDP, CPI, PPI, PMI, Shibor, LPR, Libor, Hibor, etc.	Tushare Pro · Qveris*
company_performance	Dados de empresas de ações A, financeiros, dividendos, acionistas e valuation	Tushare Pro · Qveris*
company_performance_hk	Demonstrações de resultados, balanços e fluxos de caixa de ações de Hong Kong	Tushare Pro · Qveris*
company_performance_us	Demonstrações financeiras e indicadores de ações dos EUA	Tushare Pro · Qveris*
fund_data	Valor patrimonial de fundos, posições, dividendos e informações básicas	Tushare Pro
fund_manager_by_name	Consulta de gestores de fundos e fundos gerenciados	Tushare Pro
convertible_bond	Dados do ciclo de vida completo de títulos conversíveis	Tushare Pro
block_trade	Detalhes de transações em bloco	Tushare Pro
money_flow	Fluxos de capital de ações individuais, mercado, setores e conectividade	Tushare Pro
margin_trade	Dados de margem e empréstimo de títulos	Tushare Pro
csi_index_constituents	Desempenho de índices CSI, pesos de componentes e resumo financeiro	Tushare Pro · Qveris*
dragon_tiger_inst	Detalhes de transações institucionais no ranking Dragon-Tiger	Tushare Pro
hot_news_7x24	Destaques financeiros 7×24 e deduplicação de conteúdo	Tushare Pro · Twingly* · Qveris*
futures_data	Ranking de posições de membros em futuros	Tushare Pro

Qveris* é uma camada de roteamento dinâmico de capacidades de dados que seleciona automaticamente o provedor real integrado (por exemplo, Finnhub, Tiingo, etc.) conforme a consulta; o provedor final selecionado, o ID da capacidade e a fonte dos dados são retornados junto com o resultado da Tool. Tools sem marcação Qveris retornam explicitamente "interface não coberta" e depois fazem fallback para as fontes de dados nativas da tabela.

📊 Indicadores Técnicos

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

stock_data pré-busca automaticamente os dados históricos adicionais necessários para os indicadores e, após o cálculo, corta para o intervalo solicitado pelo usuário. Solicitações com indicadores técnicos mantêm o uso de fontes de dados nativas, garantindo estabilidade nos formatos de cálculo e exibição existentes.

🛠️ Desenvolvimento 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/ e build/ são artefatos gerados localmente e não são rastreados pelo Git. A publicação no npm usa prepare para build automático, empacotando apenas o build/ necessário para execução.

🛡️ Design de Segurança

• A API Key é lida apenas do Header da solicitação ou de variáveis de ambiente, nunca gravada no repositório.
• As credenciais de solicitações HTTP são isoladas por solicitação; Headers sensíveis aparecem como [REDACTED] nos logs.
• QVERIS_BASE_URL força HTTPS por padrão; apenas endereços loopback permitem HTTP para testes de regressão.
• As capacidades candidatas do Qveris passam por filtro somente leitura, Probe de parâmetros, limite de tamanho de resposta e controle de timeout.
• .env, diretórios de dependências, artefatos de build, logs e materiais de pesquisa locais são gerenciados por regras de Git ignore.

⭐ Tendência de Stars

Se o FinanceMCP for útil para você, sinta-se à vontade para dar uma ⭐. O gráfico de tendências é atualizado automaticamente toda segunda-feira pelas GitHub Actions do próprio repositório, com suporte a atualização manual; usa o GITHUB_TOKEN temporário do repositório, sem depender de serviços de terceiros para coleta de Stars ou credenciais de longo prazo.

🤝 Ecossistema e Contribuições

• O FinanceMCP pode ser usado como backend de dados financeiros para o FinNote / MarkiNote.
• Experiência online: o serviço de hospedagem pública está temporariamente suspenso; o domínio pode ser alterado no futuro.
• Diretórios do ecossistema MCP: Glama · Smithery · MCP Toplist
• Tutorial em vídeo: Guia completo de uso do FinanceMCP
• Bugs e sugestões de recursos: GitHub Issues

Contribuições via Issue ou Pull Request são bem-vindas. Ao adicionar novas capacidades de dados, priorize a compatibilidade com os Tools agregados existentes, evitando a expansão superficial de uma Tool por interface.

📄 Licença

MIT