12306-mcp

基于 Model Context Protocol (MCP) 的12306购票搜索服务器。提供了简单的API接口，允许大模型利用接口搜索12306购票信息。

🚩Features

⚙️Installation

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

▶️Quick Start

CLI-stdio

npx -y 12306-mcp

CLI-http

npx -y 12306-mcp --port [端口号]

MCP sever configuration

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

Docker-stdio

docker build . -t 12306-mcp
docker run --rm -it 12306-mcp npx 12306-mcp

Docker-http

docker build . -t 12306-mcp
docker run -p [your_port]:8080 -d 12306-mcp npx 12306-mcp --port 8080

📚Documentation

• 服务原理详解 12306-MCP服务的工作原理
• 架构图 12306-MCP服务的架构图

👉️Reference

• modelcontextprotocol/modelcontextprotocol
• modelcontextprotocol/typescript-sdk

💭Murmurs

本项目仅用于学习，欢迎催更。

🎫Badges

☕️Donate

请我喝杯奶茶吧。

12306-mcp 快速上手指南

12306-mcp 是一个基于 Model Context Protocol (MCP) 的服务器工具，旨在让大语言模型能够直接调用接口搜索中国铁路 12306 的购票信息（包括余票查询、过站查询及中转方案等）。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Node.js：建议安装 LTS 版本（项目基于 TypeScript 开发）
• npm：随 Node.js 自动安装，用于包管理
• 可选依赖：
  • 若使用 Docker 方式运行，需安装 Docker 及 Docker Compose。
  • 若需本地开发修改，需安装 Git。

安装步骤

您可以选择通过源码安装或直接使用 npx 运行（推荐）。

方式一：源码安装（适合开发者）

1. 克隆项目仓库：

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

2. 进入目录并安装依赖：

   cd 12306-mcp
   npm i
   

   提示：如果在国内安装依赖速度较慢，可配置淘宝镜像源加速：

   npm config set registry https://registry.npmmirror.com
   npm i
   

方式二：直接使用 (无需下载代码)

本项目支持通过 npx 直接运行，无需手动克隆和安装依赖，系统会自动拉取最新包。

基本使用

根据您的使用场景，选择以下任一方式启动服务：

1. CLI 标准输入输出模式 (stdio)

适用于本地调试或直接对接支持 stdio 的 MCP 客户端（如 Cursor, Claude Desktop 等）。

npx -y 12306-mcp

2. CLI HTTP 服务模式

适用于将服务部署为独立的 HTTP 服务器，供远程调用。

npx -y 12306-mcp --port 8080

将 8080 替换为您需要的端口号。

3. 集成到 MCP 客户端配置

如果您需要在 AI 编辑器或 Agent 框架中永久集成该工具，请在 MCP 配置文件（通常为 mcp.json 或 settings.json）中添加以下配置：

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

4. Docker 容器化运行

适用于隔离环境或服务器部署。

构建镜像：

docker build . -t 12306-mcp

运行 (stdio 模式)：

docker run --rm -it 12306-mcp npx 12306-mcp

运行 (HTTP 模式)：

docker run -p 8080:8080 -d 12306-mcp npx 12306-mcp --port 8080

请将左侧的 8080 映射为您宿主机的实际端口。

---

注：本项目仅用于学习与技术交流，请遵守 12306 官方使用规范。