MCP 指南deprecated

MCP 历史安装草案（未公开）

保留的 MCP 架构草案，不代表 RailWise 已对外发布安装包、服务端或配置方式。

复核 2026-07-20入门不进入公开索引RailWise 技术团队

MCP 指南

RailWise MCP Server 安装与配置

1. 环境要求

1.1 系统要求

环境	最低版本	推荐版本	说明
Node.js	18.0.0	20.x LTS	运行时环境，必须安装
npm	9.0.0	10.x	包管理器，随 Node.js 安装
操作系统	-	macOS 14+ / Windows 11 / Ubuntu 22.04	支持主流桌面和服务器系统
内存	512 MB	1 GB	运行时的内存占用
网络	-	稳定互联网连接	访问 RailWise API 服务

1.2 AI 客户端要求

AI 客户端	最低版本	传输方式	说明
Claude Desktop	0.8.0	stdio	通过标准输入输出通信
Cursor	0.45.0	stdio	通过标准输入输出通信
Windsurf	1.0.0	stdio	通过标准输入输出通信
Cline	3.0.0	stdio	通过标准输入输出通信

注意：当前版本仅支持 stdio 传输方式。SSE（Server-Sent Events）传输方式将在后续版本中支持，用于远程服务器部署场景。

2. 安装方式

2.1 方式一：使用 npx 直接运行（推荐）

无需全局安装，每次运行自动获取最新版本：

npx -y @railwise/mcp-server

优点：

无需手动更新，始终使用最新版本
不污染全局 npm 包空间
适合快速试用和验证

缺点：

每次启动需要下载（如果本地无缓存）
离线环境无法使用

2.2 方式二：全局 npm 安装

# 全局安装
npm install -g @railwise/mcp-server

# 验证安装
railwise-mcp-server --version

优点：

启动速度快，无需重复下载
支持离线环境运行
可以使用本地配置文件

缺点：

需要手动执行更新命令

2.3 方式三：从源码构建

适用于需要自定义修改或贡献代码的开发者：

# 克隆仓库
git clone https://github.com/railwise/mcp-server.git
cd mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 运行开发模式
npm run dev

# 或运行生产构建
npm start

2.4 版本更新

全局安装更新

# 检查当前版本
npm list -g @railwise/mcp-server

# 更新到最新版本
npm update -g @railwise/mcp-server

# 或强制重新安装最新版本
npm install -g @railwise/mcp-server@latest

npx 缓存清理

# 清除 npx 缓存，确保下次使用最新版本
npx clear-npx-cache

# 或手动删除缓存目录
rm -rf ~/.npm/_npx

3. 配置指南

3.1 环境变量配置

RailWise MCP Server 通过环境变量进行配置，以下是所有支持的环境变量：

环境变量	必填	默认值	说明
`RAILWISE_API_KEY`	✅	-	RailWise API 访问密钥
`RAILWISE_API_URL`	❌	`https://api.railwise.cn/v1`	RailWise API 服务端点
`RAILWISE_MCP_LOG_LEVEL`	❌	`info`	日志级别：`debug`/`info`/`warn`/`error`
`RAILWISE_MCP_LOG_FILE`	❌	-	日志文件路径，默认输出到 stderr
`RAILWISE_MCP_TIMEOUT`	❌	`30000`	API 请求超时时间（毫秒）
`RAILWISE_MCP_MAX_RETRIES`	❌	`3`	API 请求失败时的最大重试次数
`RAILWISE_MCP_TRANSPORT`	❌	`stdio`	传输方式：`stdio`/`sse`
`RAILWISE_MCP_SSE_PORT`	❌	`3000`	SSE 传输时的监听端口
`NODE_ENV`	❌	`production`	运行环境：`development`/`production`

3.2 获取 API Key

登录 RailWise 开发者平台
进入 “API 管理” → “密钥管理”
点击 “创建新密钥”
填写密钥名称（如 “Claude Desktop 集成”）
选择权限范围（建议根据最小权限原则选择）
复制生成的 API Key（注意：密钥只显示一次，请妥善保存）

安全提示：API Key 相当于您的账户密码，请勿将其提交到代码仓库或分享给他人。建议使用环境变量或本地配置文件管理密钥。

3.3 AI 客户端配置

Claude Desktop 配置

编辑 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "railwise": {
      "command": "npx",
      "args": ["-y", "@railwise/mcp-server"],
      "env": {
        "RAILWISE_API_KEY": "rw_live_xxxxxxxxxxxxxxxx",
        "RAILWISE_API_URL": "https://api.railwise.cn/v1",
        "RAILWISE_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Cursor 配置

编辑 Cursor MCP 配置文件：

macOS：~/.cursor/mcp.json
Windows：%USERPROFILE%/.cursor/mcp.json

{
  "mcpServers": {
    "railwise": {
      "command": "npx",
      "args": ["-y", "@railwise/mcp-server"],
      "env": {
        "RAILWISE_API_KEY": "rw_live_xxxxxxxxxxxxxxxx",
        "RAILWISE_API_URL": "https://api.railwise.cn/v1"
      }
    }
  }
}

Windsurf 配置

编辑 Windsurf 配置文件：

macOS：~/.windsurf/mcp_config.json
Windows：%USERPROFILE%/.windsurf/mcp_config.json

{
  "mcpServers": {
    "railwise": {
      "command": "npx",
      "args": ["-y", "@railwise/mcp-server"],
      "env": {
        "RAILWISE_API_KEY": "rw_live_xxxxxxxxxxxxxxxx",
        "RAILWISE_API_URL": "https://api.railwise.cn/v1"
      }
    }
  }
}

3.4 使用本地配置文件

对于全局安装的用户，可以创建本地配置文件简化管理：

# 创建配置文件目录
mkdir -p ~/.config/railwise-mcp

# 创建配置文件
cat > ~/.config/railwise-mcp/config.json << 'EOF'
{
  "apiKey": "rw_live_xxxxxxxxxxxxxxxx",
  "apiUrl": "https://api.railwise.cn/v1",
  "logLevel": "info",
  "timeout": 30000,
  "maxRetries": 3
}
EOF

然后在 AI 客户端配置中指定配置文件路径：

{
  "mcpServers": {
    "railwise": {
      "command": "railwise-mcp-server",
      "args": ["--config", "~/.config/railwise-mcp/config.json"]
    }
  }
}

4. 验证安装

4.1 命令行验证

# 检查版本
npx @railwise/mcp-server --version
# 输出：@railwise/mcp-server/1.2.0

# 检查配置
npx @railwise/mcp-server --check-config
# 输出：✓ API Key 有效
#       ✓ API 服务端点可访问
#       ✓ 权限验证通过

# 查看可用工具列表
npx @railwise/mcp-server --list-tools
# 输出：Available tools (12):
#       - railwise_query_monitoring_data
#       - railwise_query_project_info
#       - railwise_query_device_status
#       ...

4.2 AI 客户端验证

配置完成后，在 AI 助手中发送以下消息验证连接：

用户：RailWise MCP 连接状态如何？

AI：RailWise MCP Server 连接正常。当前可用工具：

railwise_query_monitoring_data — 查询监测数据

railwise_query_project_info — 查询项目信息

railwise_query_device_status — 查询设备状态

…（共 12 个工具）

您可以通过我直接访问 RailWise 的监测数据和工程计算能力。

5. 多环境配置

5.1 开发/测试/生产环境切换

{
  "mcpServers": {
    "railwise-dev": {
      "command": "npx",
      "args": ["-y", "@railwise/mcp-server"],
      "env": {
        "RAILWISE_API_KEY": "rw_test_xxxxxxxxxxxxxxxx",
        "RAILWISE_API_URL": "https://api-staging.railwise.cn/v1",
        "RAILWISE_MCP_LOG_LEVEL": "debug"
      }
    },
    "railwise-prod": {
      "command": "npx",
      "args": ["-y", "@railwise/mcp-server"],
      "env": {
        "RAILWISE_API_KEY": "rw_live_xxxxxxxxxxxxxxxx",
        "RAILWISE_API_URL": "https://api.railwise.cn/v1",
        "RAILWISE_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

5.2 企业内部部署

对于需要内网部署的企业客户，可以配置私有 API 网关：

{
  "mcpServers": {
    "railwise-internal": {
      "command": "npx",
      "args": ["-y", "@railwise/mcp-server"],
      "env": {
        "RAILWISE_API_KEY": "rw_live_xxxxxxxxxxxxxxxx",
        "RAILWISE_API_URL": "https://internal-api.company.com/railwise/v1",
        "RAILWISE_MCP_TIMEOUT": "60000"
      }
    }
  }
}

6. 卸载

# 全局卸载
npm uninstall -g @railwise/mcp-server

# 清理配置文件（可选）
rm -rf ~/.config/railwise-mcp

7. 常见问题

问题	原因	解决方案
`command not found: npx`	Node.js 未安装或未加入 PATH	重新安装 Node.js，确保 npm 和 npx 在 PATH 中
`API Key 无效`	密钥错误或已过期	在开发者平台重新生成 API Key
`连接超时`	网络问题或 API 服务不可用	检查网络连接，确认 API URL 配置正确
`权限不足`	API Key 权限范围不足	在开发者平台调整密钥权限
`AI 客户端无法识别工具`	MCP 配置格式错误	检查 JSON 格式，确认路径和参数正确

8. 相关文档

MCP Server 概述 — 功能介绍和适用场景
MCP Server 工具列表 — 完整的工具清单和参数说明
MCP Server 集成示例 — 与主流 AI 平台的详细集成教程
MCP Server 安全与认证 — 认证方式和权限控制
TypeScript SDK — 使用 TypeScript SDK 自定义开发
Python SDK — 使用 Python SDK 自定义开发

本文档由 RailWise 技术文档团队维护，最后更新于 2025-01-15。