linker-ship-mcp

船舶数据 MCP Server，提供船舶实时位置、档案检索、靠泊记录、历史轨迹、每日快照、港口信息、监控区域、船队状态等查询能力，并支持船舶主数据的新建/编辑。

功能概览

共 11 个工具（9 个只读查询 + 2 个写操作）。

只读查询

| 工具 | 数据源 | 说明 | |------|--------|------| | search_ships | 船舶实时位置 | 按船名/MMSI/IMO/船型搜索，返回当前位置、航行状态与装载状态（含 Kpler 空载/重载、在船货量） | | find_ship | 船舶档案 | 按任意标识/船型/载重吨/建造年份等检索船舶档案（不依赖实时位置） | | get_ship_info | 船舶档案 | MMSI/IMO 查询单船完整静态信息（尺度/载重/舱容/船东/制裁） | | get_ship_berthing | 靠泊记录 | 多维查询靠泊记录（按船/港口/国家/码头/船型/装卸类型） | | get_ship_track | 历史轨迹 | AIS 轨迹点（TSV 格式，约省 40% token）；支持按 IMO 归一查询完整历史 | | get_ship_snapshots | 每日快照 | 按 IMO 查每日快照，对比逐日动态变化（位置/目的港/装载状态） | | query_port | 港口信息 | 港口在港船舶(ships) / 靠泊统计(stats) / 进出港事件(events) | | query_area_monitor | 监控区域 | 列出监控区域 或 查看区域最新快照的进出/变化动态 | | get_fleet_status | 船队状态 | 列出用户船队 或 查看船队成员实时位置（只读） |

写操作（会改动船舶主数据，后端写 ship_change_logs 留痕）

| 工具 | 说明 | |------|------| | create_ship | 新建船舶主数据（imo/mmsi 必填，imo 唯一） | | update_ship | 按 IMO 编辑船舶主数据（仅白名单字段，自动记录字段级新旧值） |

数据来源：Linker 船舶数据库（linker_ship），实时位置约 5-10 分钟更新。

快速开始

安装依赖 & 构建

cd packages/linker-ship-mcp
npm install
npm run build

本地测试

node dist/index.js

看到 linker-ship-mcp started 即启动成功。

客户端配置

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "linker-ship": {
      "command": "npx",
      "args": ["-y", "linker-ship-mcp@latest"],
      "env": {
        "SHIP_API_BASE": "http://hub.linker.net/api/mcp-ship",
        "SHIP_API_KEY": "<YOUR_SHIP_API_KEY>"
      }
    }
  }
}

Cursor（编辑器 MCP）

.cursor/mcp.json，结构同上。

Claude Code（CLI）

项目根目录 .mcp.json：

{
  "mcpServers": {
    "linker-ship": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "linker-ship-mcp@latest"],
      "env": {
        "SHIP_API_BASE": "http://hub.linker.net/api/mcp-ship",
        "SHIP_API_KEY": "<YOUR_SHIP_API_KEY>"
      }
    }
  }
}

或命令行：

claude mcp add linker-ship \
  --env SHIP_API_BASE=http://hub.linker.net/api/mcp-ship \
  --env SHIP_API_KEY=<YOUR_SHIP_API_KEY> \
  -- npx -y linker-ship-mcp@latest

环境变量说明

| 变量 | 必填 | 说明 | |------|------|------| | SHIP_API_BASE | 否 | 船舶 API 地址，默认 http://hub.linker.net/api/mcp-ship | | SHIP_API_KEY | 是 | 船舶 API 认证 Key（请求头 X-MCP-Key）。必填，缺失时服务启动即报错。请向管理员申请，不要提交到代码库 | | REQUEST_TIMEOUT | 否 | 单次请求超时(ms)，默认 15000 |

发布

cd packages/linker-ship-mcp
npm run build
npm publish --access public

技术栈

• TypeScript (ESM) + Node.js >= 18
• @modelcontextprotocol/sdk — MCP 协议 SDK
• zod — 参数校验