12306-mcp: servidor de consulta de bilhetes de trem com base no protocolo MCP

12306-mcp 是一个基于 Modelo de protocolo de contexto (MCP) 的火车票查询服务器，专为查询中国铁路12306票务信息设计。它提供简单易用的 API 接口，让用户或开发者通过程序快速获取实时火车票信息。项目托管在 GitHub，由开发者 Joooook 创建，旨在为 AI 助手或自动化工具提供高效的票务查询支持。服务器支持查询余票、列车信息、经停站和中转方案，适合需要快速获取票务数据的场景。项目仅用于学习，强调不存储或篡改官方数据，注重接口的简洁性和实用性。

Lista de funções

• Verifique as informações sobre as passagens de trem 12306, incluindo passagens restantes, número de trens, tipos de assentos e horários.
• Filtrar informações sobre trens, com suporte à filtragem por horário, tarifa ou tipo de trem.
• Pesquise informações sobre paradas de trem, obtenha cidades de passagem e horários de parada.
• Apoiar a consulta de trânsito e fornecer orientação sobre o programa de intercâmbio em um único local.
• Fornece uma interface API simples para facilitar a integração com assistentes de IA ou programas de automação.
• Oferece suporte à pesquisa difusa de informações de estações em todo o país, facilitando a localização rápida de estações.

Usando a Ajuda

Processo de instalação

Para usar o servidor 12306-mcp, siga as etapas abaixo para implantá-lo localmente ou em um servidor:

1. Clonagem do código do projeto
   Use o comando Git para fazer o download do código-fonte do projeto:

   git clone https://github.com/Joooook/12306-mcp.git
   

2. Instalação de dependências
   Vá para o diretório do projeto e instale as dependências do Node.js:

   cd 12306-mcp
   npm i
   

3. Criar o projeto
   Execute o comando de compilação para gerar o executável:

   npm run build
   

4. Iniciar o servidor
   Execute o seguinte comando para iniciar o servidor:

   node ./build/index.js
   

5. Configuração do servidor MCP
   Se precisar integrar o 12306-mcp em um sistema compatível com o protocolo MCP, adicione o seguinte ao arquivo de configuração:

   {
   "mcpServers": {
   "12306-mcp": {
   "command": "npx",
   "args": ["-y", "12306-mcp"]
   }
   }
   }
   

   O caminho do arquivo de configuração geralmente está localizado no cliente ou na plataforma compatível com o protocolo MCP. Consulte a documentação do sistema de destino para obter o caminho específico.

Uso

Após a implantação, o 12306-mcp fornece um conjunto de interfaces de API que os desenvolvedores ou assistentes de IA podem chamar por meio de solicitações HTTP. Veja a seguir o fluxo de operação das principais funções:

1. procure informações sobre passagens de trem

Os usuários podem enviar solicitações por meio da API para consultar informações sobre passagens de trem para uma data, origem e destino especificados. Por exemplo, consultar passagens de trem de Pequim para Xangai:

• Exemplo de solicitação de API::

  GET /tickets?from=Beijing&to=Shanghai&date=2025-07-22
  

• Dados de retornoFormato JSON, incluindo número de trens, horário de partida, horário de chegada, tarifa, número de bilhetes restantes, etc.
• procedimento::
  1. Determine a origem, o destino e a data.
  2. Envie uma solicitação GET usando um cliente HTTP (como o Postman) ou um código.
  3. Analisa os dados JSON retornados para obter as viagens e tarifas disponíveis.
• tomar nota dePartida e destino precisam usar o nome ou código oficial da estação 12306, com suporte à busca difusa.

2. filtragem das informações do trem

Os usuários podem filtrar os trens de acordo com suas necessidades, como visualizar apenas os trens de alta velocidade ou os trens noturnos:

• Exemplo de solicitação de API::

  GET /tickets?from=Beijing&to=Shanghai&date=2025-07-22&type=highspeed
  

• procedimento::
  1. Adicione parâmetros de filtro à solicitação, como type=highspeed(Trem de alta velocidade) ou time=night(à noite).
  2. O servidor retorna uma lista de viagens elegíveis.
  3. Os usuários podem ainda classificar por tarifa ou duração.

3. pesquisar paradas

Informe-se sobre as paradas e os horários de parada de um determinado trem:

• Exemplo de solicitação de API::

  GET /train/stops?trainNo=G123
  

• Dados de retornoFormato JSON com o nome da estação de passagem, hora de chegada e hora da escala.
• procedimento::
  1. Obtenha o número do trem de destino (por exemplo, G123).
  2. Envie uma solicitação para obter uma lista de paradas.
  3. Você pode combiná-lo com a ferramenta de mapa para gerar dicas de viagem e planejar seu itinerário para as cidades pelas quais está passando.

4. consultas de trânsito

Para rotas sem trens diretos, o servidor oferece opções de trânsito:

• Exemplo de solicitação de API::

  GET /transfer?from=Xian&to=Zhengzhou&date=2025-07-22
  

• Dados de retorno: Escalas recomendadas, tempos de transferência e tempo total de viagem.
• procedimento::
  1. Digite a origem, o destino e a data.
  2. Programa de trânsito de retorno do servidor, por exemplo, número específico de trens e horário de transferência em Wuhan.
  3. Os usuários podem escolher a opção ideal com base na duração total ou na tarifa.

5. estações de pesquisa difusa

Suporta a entrada de nomes parciais de estações para encontrar informações completas:

• Exemplo de solicitação de API::

  GET /stations?name=Hang
  

• Dados de retornoInclui informações detalhadas sobre a estação "Hangzhou" e "Hangzhou East".
• procedimento::
  1. Digite parte do nome da estação em pinyin ou caracteres chineses.
  2. O servidor retorna uma lista de estações correspondentes.
  3. Selecione o código correto da estação na lista para usar na consulta de bilhetes.

advertência

• Fonte de dadosTodos os dados de tíquetes vêm da interface oficial 12306, o servidor apenas agrega e encaminha, não armazena dados.
• risco de usoRecomendamos que a frequência das solicitações seja definida de forma razoável.
• Suporte ao desenvolvimentoO projeto convida os desenvolvedores a contribuir com novos recursos, e as solicitações de recursos podem ser enviadas pelo GitHub.

cenário do aplicativo

1. Integração do assistente de IA
   O 12306-mcp pode ser incorporado a assistentes de IA (por exemplo, chatbots inteligentes), para que os usuários possam inserir "passagens de trem de Xangai para Hangzhou amanhã" por voz ou texto, e o assistente chamará a API para retornar informações sobre passagens em tempo real e fornecer rapidamente o número de viagens de trem e tarifas.
2. Ferramentas de planejamento de viagens
   Os desenvolvedores podem integrar o 12306-mcp em seus aplicativos de planejamento de viagens, combinando informações de paradas para gerar guias de viagem para as cidades pelas quais estão viajando. Por exemplo, se você estiver procurando um trem de Pequim para Guangzhou, poderá recomendar atrações em Wuhan.
3. Consulta automatizada de emissão de bilhetes
   As empresas podem usar o 12306-mcp para desenvolver ferramentas automatizadas de monitoramento de bilhetes para rastrear os bilhetes restantes em uma determinada rota em tempo real, o que é adequado para cenários de gerenciamento de viagens ou agências de bilhetes.
4. Educação e pesquisa
   Os alunos ou desenvolvedores podem usar o 12306-mcp para aprender a implementação do protocolo MCP e estudar como agregar dados de terceiros por meio da API, adequada para cursos de informática ou prática de projetos de código aberto.

QA

1. Há alguma taxa para o 12306-mcp?
   O projeto é totalmente de código aberto, de uso gratuito, hospedado no GitHub e requer apenas a autoimplantação do servidor.
2. Ele oferece suporte a atualizações de tíquetes em tempo real?
   Sim, o servidor obtém dados em tempo real por meio da interface oficial 12306 para garantir informações precisas sobre os tíquetes.
3. Como evitar a ativação do mecanismo anti rastreamento do 12306?
   Recomenda-se definir intervalos de solicitação razoáveis (por exemplo, não mais do que 5 vezes por minuto) para evitar solicitações de alta frequência em um curto período de tempo.
4. Posso usá-lo diretamente no meu celular?
   Atualmente, ele precisa ser implantado em um computador ou servidor, e os telefones celulares podem acessá-lo por meio de um cliente de API ou aguardar uma possível adaptação futura para dispositivos móveis.
5. Quais linguagens de programação são suportadas para chamar a API?
   A API usa o protocolo HTTP padrão e pode ser chamada por qualquer linguagem que ofereça suporte a solicitações HTTP (por exemplo, Python, JavaScript).