内容
# 船舶交通MCP
<p align="center">
<a href="#在MCP客户端安装">English</a> |
<a href="#한국어">한국어</a> |
<a href="#日本語">日本語</a> |
<a href="#中文">中文</a>
</p>
<p align="center">
<a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
<a href="https://www.npmjs.com/package/@tools-mcp/vessel-traffic-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@tools-mcp/vessel-traffic-mcp"></a>
<a href="https://www.npmjs.com/package/@tools-mcp/vessel-traffic-mcp"><img alt="npm downloads" src="https://img.shields.io/npm/dw/@tools-mcp/vessel-traffic-mcp"></a>
<a href="https://github.com/tools-mcp/vessel-traffic-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/tools-mcp/vessel-traffic-mcp/actions/workflows/ci.yml/badge.svg"></a>
<a href="https://github.com/tools-mcp/vessel-traffic-mcp/releases"><img alt="GitHub release" src="https://img.shields.io/github/v/release/tools-mcp/vessel-traffic-mcp"></a>
<a href="https://github.com/tools-mcp/vessel-traffic-mcp/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/tools-mcp/vessel-traffic-mcp?style=social"></a>
</p>
<p align="center">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.tools-mcp%2Fvessel-traffic-mcp"><img alt="MCP Registry: published" src="https://img.shields.io/badge/MCP%20Registry-published-0f766e"></a>
<a href="https://tools-mcp.github.io/vessel-traffic-mcp/"><img alt="Agent landing page" src="https://img.shields.io/badge/Agent%20Landing%20Page-live-08736d"></a>
<a href="https://github.com/tools-mcp/vessel-traffic-mcp/issues"><img alt="GitHub issues" src="https://img.shields.io/github/issues/tools-mcp/vessel-traffic-mcp"></a>
<a href="https://github.com/tools-mcp/vessel-traffic-mcp/network/members"><img alt="GitHub forks" src="https://img.shields.io/github/forks/tools-mcp/vessel-traffic-mcp"></a>
</p>
**用于AI代理的船舶跟踪和航运时刻表。**
<p align="center">
<img src="./docs/marketing/assets/map-ui-ever-given.png" alt="Local Vessel Traffic MCP map UI showing EVER GIVEN with source attribution" width="860">
</p>
船舶交通MCP是一个只读的**模型上下文协议（MCP）服务器**，用于船舶身份查找、AIS样式的位置、轨迹、港口调用、航运时刻表、船舶时刻表和延迟启发式。它为Claude、ChatGPT、Codex、MCP Inspector和其他MCP客户端提供了一个规范的海上数据工具表面。
在以下情况下使用：
- 通过通用连接器样式的MCP工具搜索/获取船舶上下文；
- 从名称、MMSI、IMO、呼号或提单文本中解析船舶；
- 查询船舶当前位置、历史轨迹或指定区域内的船舶；
- 按港口对或船舶搜索集装箱航运时刻表；
- 返回原始提供者和每个实时/公开结果的源URL；
- 在购买付费AIS或时刻表API之前安全测试海上工作流。
该项目不会绕过提供商的条款、付费墙、验证码或访问控制。商业提供商采用自带密钥（BYOK），默认测试路径仅限于fixture，本项目不是导航产品。
在 [MIT许可证](./LICENSE) 下开源。预1.0；API和工具表面可能会更改。
## 目录
- [在MCP客户端安装](#在MCP客户端安装)
- [代理发现页面](#代理发现页面)
- [公开内容](#公开内容)
- [提供商模型](#提供商模型)
- [帮助传播](#帮助传播)
- [从源代码](#从源代码)
- [远程HTTP设置](#远程HTTP设置)
- [当前分发](#当前分发)
- [星历史](#星历史)
- [共享参考](#共享参考)
## 在MCP客户端安装
对于Claude Desktop、Claude Code、Codex CLI、Cursor、VS Code或任何stdio MCP客户端，请使用npm包：
```json
{
"mcpServers": {
"vessel-traffic-mcp": {
"command": "npx",
"args": ["-y", "@tools-mcp/vessel-traffic-mcp"],
"env": {
"VESSEL_MCP_TRANSPORT": "stdio",
"VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS": "myshiptracking,tradlinx"
}
}
}
}
```
然后重启客户端并尝试：
```text
查找EVER GIVEN的当前位置。包括source.provider和source.landingUrl。
搜索从KRPUS到NLRTM的航运时刻表。包括源URL。
```
完整的客户端设置位于
[`docs/runbooks/clients.md`](./docs/runbooks/clients.md)，Codex
详细信息位于 [`docs/runbooks/codex.md`](./docs/runbooks/codex.md)。
源代码检查配置片段位于
[共享MCP配置片段](#共享MCP配置片段)。
市场和AI客户端提交助手位于
[`llms-install.md`](./llms-install.md)、 [`LAUNCHGUIDE.md`](./LAUNCHGUIDE.md)和
[`assets/logo-400.png`](./assets/logo-400.png)。
## 代理发现页面
公开的代理搜索和安装代码段的登陆页面是：
https://tools-mcp.github.io/vessel-traffic-mcp/
使用该URL分享项目作为**船舶AIS MCP**、**船舶跟踪MCP**、**ChatGPT MCP**、**Codex MCP**、**Claude MCP**或**Gemini MCP**服务器。
该页面包括`EVER GIVEN`场景的黄金提示和本地stdio和远程Streamable HTTP设置的客户端代码段。
辅助服务不会自动发现任意MCP服务器。操作员必须首先连接此MCP；之后，工具描述、`search`/`fetch`包装器和特定于船舶的工具为代理提供从船舶名称提示到源属性结果的清晰路径。
## 公开内容
| 区域 | 只读工具 |
| --- | --- |
| 搜索样式的连接器流程 | `search`, `fetch` |
| 船舶身份 | `vessel_search`, `vessel_name_resolve`, `document_vessel_lookup` |
| AIS样式的移动 | `vessel_position`, `vessel_area`, `vessel_track` |
| 港口活动 | `port_calls` |
| 航运时刻表 | `carrier_schedule_search`, `vessel_schedule`, `schedule_delay_predict` |
| 提供商设置 | `provider_status`, `data_sources`, `credential_profiles`, `provider_onboarding` |
每个实时或公共提供商的响应必须公开出处：`source.provider`和`source.landingUrl`。该项目旨在引导用户返回原始服务，而不是隐藏或重新品牌化数据源。
## 提供商模型
| 提供商组 | 如何启用 | 备注 |
| --- | --- | --- |
| Fixture | 默认 | 确定性测试和演示；无网络、帐户或API密钥 |
| 公共选择加入 | `VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx` | 公共Web适配器，带有源属性 |
| BYOK商业/社区API | `VESSEL_MCP_ENABLE_BYOK_PROVIDERS=...` 加 `VESSEL_MCP_PROFILE_*` 环境变量 | 用户拥有凭证；日志、错误和MCP响应中会遮蔽机密 |
| 远程部署 | `VESSEL_MCP_TRANSPORT=http` | 流式HTTP在`/mcp`; 设置`VESSEL_MCP_AUTH_TOKEN`进行`Authorization: Bearer <token>` |
使用`provider_onboarding`MCP工具检查提供商的注册URL、所需的环境变量、配置的配置文件状态和验证步骤。它是只读的，永远不会创建帐户、接受条款、解决验证码、完成电子邮件验证、设置付款详细信息或颁发API密钥。
## 帮助传播
如果这能帮助某人构建MCP工具、航运/物流软件或围绕海上数据的AI工作流，请分享仓库并请求实际的工作流反馈。复制/粘贴分享工具位于
[`docs/marketing/help-us-spread.md`](./docs/marketing/help-us-spread.md)。
有用的帮助包括尝试npm安装、发布定制的社区文章、请求提供商适配器或解释实际的转发、贸易、港口调用、船舶ETA或航运时刻表工作流。
## 从源代码
```bash
git clone https://github.com/tools-mcp/vessel-traffic-mcp.git
cd vessel-traffic-mcp
npm ci
npm run lint
npm test
npm run build
```
默认验证门控仅使用净化fixture。它不会调用付费或实时提供商，不需要API密钥、帐户或网络访问。
对于本地视觉检查，输入船舶名称并显示地图：
```bash
npm run start:map
```
打开 `http://127.0.0.1:8787` 并搜索 `EVER GIVEN` 或 MMSI `353136000`。
## 远程HTTP设置
对于远程MCP客户端，在`/mcp`处运行Streamable HTTP：
```bash
export VESSEL_MCP_TRANSPORT=http
export VESSEL_MCP_HTTP_HOST=127.0.0.1
export VESSEL_MCP_HTTP_PORT=8765
export VESSEL_MCP_AUTH_TOKEN="<a-strong-random-token-you-generated>"
npm run start:http
```
MCP请求`Authorization: Bearer <token>`时需要`VESSEL_MCP_AUTH_TOKEN`。请参阅
[`docs/runbooks/streamable-http-server.md`](./docs/runbooks/streamable-http-server.md)和
[`docs/runbooks/deployment-https.md`](./docs/runbooks/deployment-https.md)。
## 当前分发
| 表面 | 状态 | 访问 |
| --- | --- | --- |
| GitHub | 公共 | https://github.com/tools-mcp/vessel-traffic-mcp |
| 代理登陆页面 | 公共 | https://tools-mcp.github.io/vessel-traffic-mcp/ |
| npm | 公共 | `@tools-mcp/vessel-traffic-mcp@0.1.0` 在 https://www.npmjs.com/package/@tools-mcp/vessel-traffic-mcp |
| GitHub Release | 已发布 | https://github.com/tools-mcp/vessel-traffic-mcp/releases/tag/v0.1.0 |
| MCP Registry | 已发布 | `io.github.tools-mcp/vessel-traffic-mcp@0.1.0` 在 [官方注册表](https://registry.modelcontextprotocol.io/?q=io.github.tools-mcp%2Fvessel-traffic-mcp) |
| ServerHub | 已列出 | https://www.serverhub.digital/servers/vessel-traffic-mcp |
| VaultPlane | 已列出 | https://www.vaultplane.com/server/vessel-traffic-mcp |
| MCPRepository | 已提交 | 正在排队验证，网址为 https://mcprepository.com/tools-mcp/vessel-traffic-mcp |
| 本地地图UI | 已准备好从源代码 | `npm run start:map`，然后打开 `http://127.0.0.1:8787` |
| HTTP目录元数据 | 已准备好从源代码 | `npm run start:http`，然后获取 `/.well-known/mcp/server-card.json` |
| Glama | 已提交审核 | 已于2026-05-27通过Glama的添加服务器流程提交；公共列表URL和分数徽章保留在 https://glama.ai/mcp/servers/tools-mcp/vessel-traffic-mcp 且可能返回404，直到审核/索引完成 |
| PulseMCP | 提交/索引待定 | 跟踪 [`docs/runbooks/public-sharing.md`](./docs/runbooks/public-sharing.md) 和 [`docs/marketing/outreach-status.md`](./docs/marketing/outreach-status.md) |
| Smithery | HTTPS端点待定 | 需要稳定的公共HTTPS `/mcp` URL |
发布副本和目录提交材料位于
[`docs/marketing`](./docs/marketing/launch-kit.md)。
## 星历史
[
## 语言
- [English](#在MCP客户端安装)
- [한국어](#한국어)
- [日本語](#日本語)
- [中文](#中文)
### 概览
`vessel-traffic-mcp` 是一个只读 MCP 服务器，让 MCP 客户端能够通过统一工具接口访问已授权的海事数据来源。
它支持按船名、MMSI、IMO、呼号搜索船舶，查询最新位置、区域位置、港口靠泊、承运人航线计划、船舶计划和延误判断。
所有实时或公开 provider 的响应都必须包含 `source.provider` 和 `source.landingUrl`。本项目用于向原始服务导流并明确显示出处，而不是隐藏或重新包装数据来源。
### 快速开始
```bash
git clone https://github.com/tools-mcp/vessel-traffic-mcp.git
cd vessel-traffic-mcp
npm install
npm run lint
npm test
npm run build
```
默认验证只使用已清洗的 fixture，不调用付费或实时 provider，也不需要 API key、账号或网络访问。
### 本地 MCP 设置
本地桌面和 CLI 客户端使用 stdio transport。
```bash
VESSEL_MCP_TRANSPORT=stdio npm start
```
Codex CLI、Claude Desktop、Claude Code 可使用 [共享 MCP 配置片段](#共享MCP配置片段)。
### 远程 MCP 设置
远程 MCP 客户端使用 Streamable HTTP `/mcp`，`/health` 是公开健康检查。
```bash
export VESSEL_MCP_TRANSPORT=http
export VESSEL_MCP_HTTP_HOST=127.0.0.1
export VESSEL_MCP_HTTP_PORT=8765
export VESSEL_MCP_AUTH_TOKEN="<a-strong-random-token-you-generated>"
npm run start:http
```
设置 `VESSEL_MCP_AUTH_TOKEN` 后，MCP 请求需要 `Authorization: Bearer <token>`。
### 公开 Provider
浏览器捕获得到的公开 adapter 需要显式启用。
```bash
VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx npm start
```
- `myshiptracking`: 船舶自动完成、按选定 MMSI 查询最新位置、地图范围查询。
- `tradlinx`: FCL/LCL 承运人航线计划查询。
- `shipfinder`: 用于显式 provider 路由的船舶搜索和详情 API 形状。
### BYOK Provider
付费或需要 credential 的 provider 只能使用 BYOK。真实 key 不会出现在日志、错误或 MCP 响应中。
```bash
export VESSEL_MCP_PROFILE_MARINETRAFFIC__API_KEY="<your-key>"
export VESSEL_MCP_ENABLE_BYOK_PROVIDERS="marinetraffic,vesselfinder,aisstream,aishub,barentswatch,searates-schedules,routescanner-connect,vesselapi,datadocked,datalastic,globalfishingwatch"
```
当前可在 runtime 启用的 credentialed provider 是 `marinetraffic`、`vesselfinder`、`aisstream`、`aishub`、`barentswatch`、`searates-schedules`、`routescanner-connect`、`vesselapi`、`datadocked`、`datalastic`、`globalfishingwatch`。
### Agent 设置提示词
让其他编码 agent 安装此 MCP 时可使用以下提示词。
```text
请将 https://github.com/tools-mcp/vessel-traffic-mcp 安装并配置为本机
本地 stdio MCP 服务器。
先阅读 README.md 和 llms.txt。clone 仓库，运行 `npm ci` 和
`npm run build`，然后在本地 MCP 客户端中用 `dist/index.js` 的绝对路径
注册服务器。
使用 `VESSEL_MCP_TRANSPORT=stdio`，并设置
`VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS=myshiptracking,tradlinx`。
不要提交本地 MCP 客户端配置、env 文件、API key、cookie、HAR 文件、
浏览器 session 或 raw capture。不要从其他机器复制 credentials。
重启 MCP 客户端后验证：
1. 查询 EVER GIVEN 当前船位，并显示来源 URL。
2. 查询 KRPUS 到 NLRTM 的承运人航线计划，并显示来源 URL。
```
## 共享参考
### 共享 MCP 配置片段
Codex CLI `~/.codex/config.toml`:
```toml
[mcp_servers.vessel-traffic-mcp]
command = "node"
args = ["/absolute/path/to/vessel-traffic-mcp/dist/index.js"]
[mcp_servers.vessel-traffic-mcp.env]
VESSEL_MCP_TRANSPORT = "stdio"
VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS = "myshiptracking,tradlinx"
```
Claude Desktop / Claude Code 配置:
```json
{
"mcpServers": {
"vessel-traffic-mcp": {
"command": "node",
"args": ["/absolute/path/to/vessel-traffic-mcp/dist/index.js"],
"env": {
"VESSEL_MCP_TRANSPORT": "stdio",
"VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS": "myshiptracking,tradlinx"
}
}
}
}
```
### Provider 实现状态
The PRD is intentionally broader than the adapters enabled by default.
当前状态：
| 分组 | 运行状态 | 提供者 |
| --- | --- | --- |
| 默认 | 已启用，无需环境变量 | `fixture` |
| 公开，需选择加入 | `VESSEL_MCP_ENABLE_PUBLIC_PROVIDERS` | `myshiptracking`、`shipfinder`、`tradlinx-schedule` |
| 已实施，需凭证 | `VESSEL_MCP_ENABLE_BYOK_PROVIDERS` 或配置默认配置文件 | `marinetraffic`、`vesselfinder`、`aisstream`、`aishub`、`barentswatch`、`searates-schedules`、`routescanner-connect`、`vesselapi`、`datadocked`、`datalastic`、`globalfishingwatch` |
| 计划中的调度 API | 已编目，尚未实施 | `linescape-schedule-api` |
| 未启动的商业 AIS | 已编目，尚未实施 | `spire-maritime`、`orbcomm-commtrace` |
| 发现或企业审查 | 仅编目 | `openais`、`noaa-marinecadastre`、`iqax-bigschedules`、`cargosmart-schedule`、`poseidon-ais`、`ais-now`、`fleetmon`、`windward`、`polestar-global`、`spglobal-seaweb`、`lloyds-list-intelligence` |
结构化数据源位于 [`config/provider-catalog.example.json`](./config/provider-catalog.example.json)，人类可读的清单位于 [`docs/provider-catalog.md`](./docs/provider-catalog.md)。
### 本地船舶地图 UI
进行本地视觉检查，输入船名并显示地图：
```bash
npm run start:map
```
打开 `http://127.0.0.1:8787` 并搜索 `EVER GIVEN` 或 MMSI `353136000`。UI 显示地图标记和可见的来源链接。
### 调度工具
已注册的只读调度工具：
- `carrier_schedule_search`
- `vessel_schedule`
- `schedule_delay_predict`
已注册的只读提供者/设置工具：
- `provider_status`
- `data_sources`
- `credential_profiles`
- `provider_onboarding`
Fixture 支持的检查：
```text
KRPUS에서 NLRTM으로 가는 선사 스케줄을 조회하고, 출처 URL도 같이 보여줘.
EVER GIVEN 선박 스케줄을 조회하고 ETA 지연 여부를 계산해줘.
```
调度提供者候选人被记录在 [`docs/provider-catalog.md`](./docs/provider-catalog.md) 中。Tradelinx 有一个明确的选择加入 `carrier_schedule_search` 适配器，支持从浏览器捕获的端点形状进行卫生检查，详见 [`docs/runbooks/schedule-api-capture-results.md`](./docs/runbooks/schedule-api-capture-results.md)。
### 捕获和安全边界
本项目不旨在绕过商业服务。它支持：
- 官方 API 和开放数据馈送。
- 用户提供的 API 凭证和组织级别的 BYOK 凭证配置文件，用于付费提供者。
- 来自运营商拥有的、授权的浏览器会话的卫生 HAR/网络样本，仅在服务条款允许的情况下。
严禁在仓库中存储原始 cookie、Bearer Token、API 密钥、私有 HAR 文件、原始捕获或私有浏览器会话。完整的安全规则列表位于 [`AGENTS.md`](./AGENTS.md)，安全期望位于 [`SECURITY.md`](./SECURITY.md)。
授权的捕获工具记录在 [`docs/runbooks/capture-execution.md`](./docs/runbooks/capture-execution.md)。卫生导入命令为 `npm run capture:import`，流量 IR 生成为 `npm run capture:ir`。
> 请勿用于导航。配置的提供者返回的 AIS 数据可能延迟、不完整或不准确。本项目不是安全关键的导航工具。
### 项目布局
```text
src/
capture/ 卫生捕获fixture导入器 + 流量IR CLI
config/ 凭证配置文件加载器，提供者目录
providers/ 适配器接口、注册表、路由器、速率限制、TTL缓存
server/ MCP传输和工具处理程序
tools/ 只读工具定义
util/ 结构化日志记录和编辑辅助函数
test/ node:test 确定性测试；fixture支持
docs/ PRD、TDD、提供者目录和操作手册
```
### 文档
- [`llms.txt`](./llms.txt) — 面向代理的项目简介。
- [`docs/index.html`](./docs/index.html) — 通过 GitHub Pages发布的静态代理发现页面。
- [`server.json`](./server.json) — `io.github.tools-mcp/vessel-traffic-mcp` 命名空间的 MCP 注册表元数据。
- [`AGENTS.md`](./AGENTS.md) — 项目硬规则。
- [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md) — 协作期望。
- [`docs/PRD.md`](./docs/PRD.md) — 产品需求。
- [`docs/TDD.md`](./docs/TDD.md) — 技术设计。
- [`docs/provider-catalog.md`](./docs/provider-catalog.md) — 提供者目录和路由策略。
- [`docs/runbooks/operator.md`](./docs/runbooks/operator.md) — 端到端操作手册。
- [`docs/runbooks/clients.md`](./docs/runbooks/clients.md) — Claude Desktop、Claude Code、ChatGPT 远程 MCP 和 MCP Inspector 的客户端设置。
- [`docs/runbooks/codex.md`](./docs/runbooks/codex.md) — Codex CLI MCP 连接和 Codex 插件元数据状态。
- [`docs/runbooks/credential-profiles.md`](./docs/runbooks/credential-profiles.md) — BYOK 配置文件处理。
- [`docs/runbooks/deployment-https.md`](./docs/runbooks/deployment-https.md) — Streamable HTTP MCP 端点的 HTTPS 部署。
- [`docs/runbooks/release-checklist.md`](./docs/runbooks/release-checklist.md) — 预发布安全检查清单。
- [`docs/runbooks/public-sharing.md`](./docs/runbooks/public-sharing.md) — GitHub、MCP 注册表、Smithery、Glama、PulseMCP 和发布后共享清单。
- [`docs/runbooks/api-capture-reference-only.md`](./docs/runbooks/api-capture-reference-only.md) — 原始捕获会话的仅参考边界。
- [`docs/runbooks/browser-api-capture-results.md`](./docs/runbooks/browser-api-capture-results.md) — 船舶 API 的卫生浏览器捕获结果。
- [`docs/runbooks/schedule-api-capture-results.md`](./docs/runbooks/schedule-api-capture-results.md) — 调度 API 的卫生浏览器捕获结果。
- [`docs/discoverability.md`](./docs/discoverability.md) — 包、仓库和文档的可发现性合约。
### 主题
`vessel-traffic-mcp` 意在从 MCP 和插件搜索界面中找到。相同的主题集合反映在 `package.json` 关键词和建议的 GitHub 主题中。
- 船舶 AIS MCP
- 船舶跟踪 MCP
- MarineTraffic MCP
- Claude MCP（Claude Desktop，Claude Code）
- ChatGPT MCP（ChatGPT 远程 MCP 连接器）
- Codex 插件（Codex / OpenAI 插件 / 市场工作流）
- Gemini MCP（Gemini CLI 和 Gemini Code Assist）
- MCP / 模型上下文协议服务器
- AIS / 船舶跟踪 / 船舶跟踪
- BYOK 付费提供者路由（MarineTraffic、VesselFinder、AISStream、AISHub、BarentsWatch、SeaRates、Routescanner、VesselAPI、Data Docked 等等）
### 贡献
欢迎贡献。请先阅读 [`CONTRIBUTING.md`](./CONTRIBUTING.md)。该项目有关于凭证、捕获fixture和只读合约的不可妥协的安全规则。
使用 GitHub Issues 进行错误、提供者请求和授权捕获审查。使用 GitHub Discussions 进行路线图、集成和协作线程。共享清单位于 [`docs/runbooks/public-sharing.md`](./docs/runbooks/public-sharing.md)。
### 安全
请勿为疑似漏洞提交公共 GitHub 问题。请参阅 [`SECURITY.md`](./SECURITY.md) 以获取私人报告渠道。
### 许可证
[MIT](./LICENSE)。请参阅 [NOTICE](./NOTICE) 以获取非导航通知。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器