使用说明

海上交通MCP服务器

用于访问海上交通船舶跟踪数据的模型上下文协议（MCP）服务器实现。该服务器提供实时船舶位置跟踪、详细船舶信息、船舶搜索功能和基于区域的船舶查询。

特性

核心船舶跟踪

获取船舶位置：按MMSI、IMO或船舶ID检索船舶的当前位置数据
获取船舶详细信息：访问全面的船舶信息，包括规格、目的地和港口数据
搜索船只：按名称、MMSI或IMO编号搜索船只
基于区域的查询：获取指定地理边界框内的所有船只

历史和航行数据

历史轨迹：随时间推移的访问船只移动历史（最多30天）
靠港：获取完整的港口停靠历史记录，包括到达和离开（最多1年）
船舶预计到达时间：通过距离和速度计算检索估计到达时间
船舶事件：获取船舶活动和重要事件的时间表

港口情报

端口详细信息：获取有关特定端口的全面信息
端口搜索：按名称或国家搜索港口

邻近与发现

附近船只：查找任何位置半径内的所有船只

先决条件

达到1.21或更高
海上交通API关键(在这里买一个)

安装

克隆存储库：

git clone <repository-url>
cd marine-traffic-mcp

安装依赖项：

go mod download

配置API密钥：

cp .env.example .env
# Edit .env and add your Marine Traffic API key

构建服务器：

go build -o marine-traffic-mcp

配置

服务器是通过环境变量配置的。创建一个 .env 项目根目录中的文件：

# Required: Your Marine Traffic API key
MARINE_TRAFFIC_API_KEY=your_api_key_here

# Optional: Override the default base URL
MARINE_TRAFFIC_BASE_URL=https://services.marinetraffic.com/api

# Optional: Enable debug mode for verbose logging
DEBUG=true

环境变量

变量	必填	默认	描述
`MARINE_TRAFFIC_API_KEY`	是	-	您的海上交通API密钥
`MARINE_TRAFFIC_BASE_URL`	没有	`https://services.marinetraffic.com/api`	API基本URL
`DEBUG`	没有	`false`	启用调试日志记录

用法

运行服务器

./marine-traffic-mcp

或者直接使用环境变量：

MARINE_TRAFFIC_API_KEY=your_key ./marine-traffic-mcp

MCP工具

服务器公开了10个按类别组织的综合MCP工具：

核心容器跟踪工具

1.获取_容器_位置

获取船只的当前位置。

参数：

vessel_id （字符串，必填）：船舶标识符
id_type （字符串，必填）：标识符类型- mmsi, imo，或 shipid

例子：

{
  "vessel_id": "371234000",
  "id_type": "mmsi"
}

答复：

{
  "mmsi": "371234000",
  "imo": "9123456",
  "ship_id": "123456",
  "lat": 37.7749,
  "lon": -122.4194,
  "speed": 12.5,
  "heading": 180,
  "course": 175,
  "status": "Under way using engine",
  "timestamp": "2025-12-05T10:30:00",
  "ship_name": "EXAMPLE VESSEL",
  "ship_type": "Cargo",
  "call_sign": "ABCD"
}

2.获取详细信息

获取有关船只的详细信息。

参数：

vessel_id （字符串，必填）：船舶标识符
id_type （字符串，必填）：标识符类型- mmsi, imo，或 shipid

例子：

{
  "vessel_id": "9123456",
  "id_type": "imo"
}

答复：

{
  "mmsi": "371234000",
  "imo": "9123456",
  "ship_id": "123456",
  "ship_name": "EXAMPLE VESSEL",
  "ship_type": "Cargo",
  "flag": "US",
  "breadth": 32,
  "length": 225,
  "draught": 12.5,
  "deadweight": 45000,
  "gross_tonnage": 30000,
  "year_built": 2015,
  "call_sign": "ABCD",
  "destination": "LOS ANGELES",
  "eta": "2025-12-06T14:00:00",
  "current_port": "SAN FRANCISCO",
  "last_port": "SEATTLE",
  "last_port_time": "2025-12-04T08:00:00",
  "current_port_id": 3489
}

3.搜索_容器

按名称、MMSI或IMO搜索船只。

参数：

query （字符串，必填）：搜索查询
search_type （字符串，必填）：搜索类型- name, mmsi，或 imo

例子：

{
  "query": "MAERSK",
  "search_type": "name"
}

答复：

[
  {
    "mmsi": "219001234",
    "imo": "9321456",
    "ship_id": "234567",
    "ship_name": "MAERSK EXAMPLE",
    "ship_type": "Container Ship",
    "flag": "DK"
  },
  {
    "mmsi": "219005678",
    "imo": "9456789",
    "ship_id": "345678",
    "ship_name": "MAERSK SAMPLE",
    "ship_type": "Container Ship",
    "flag": "DK"
  }
]

4.获取_容器_区域

获取地理边界框内的所有船只。

参数：

min_lat （数字，必填）：最小纬度（南边界）
max_lat （数字，必填）：最大纬度（北边界）
min_lon （数字，必填）：最小经度（西边界）
max_lon （数字，必填）：最大经度（东边界）

例子：

{
  "min_lat": 37.0,
  "max_lat": 38.0,
  "min_lon": -123.0,
  "max_lon": -122.0
}

答复：

[
  {
    "mmsi": "371234000",
    "imo": "9123456",
    "ship_id": "123456",
    "lat": 37.7749,
    "lon": -122.4194,
    "speed": 12.5,
    "heading": 180,
    "course": 175,
    "status": "Under way using engine",
    "timestamp": "2025-12-05T10:30:00",
    "ship_name": "EXAMPLE VESSEL",
    "ship_type": "Cargo",
    "call_sign": "ABCD"
  }
]

历史和航行跟踪工具

5.获取历史轨迹

获取船舶随时间变化的历史位置数据。

参数：

vessel_id （字符串，必填）：船舶标识符
id_type （字符串，必填）：标识符类型- mmsi, imo，或 shipid
days （数字，可选）：历史天数（1-30，默认值：3）

例子：

{
  "vessel_id": "371234000",
  "id_type": "mmsi",
  "days": 7
}

答复：

[
  {
    "mmsi": "371234000",
    "status": "Under way using engine",
    "speed": 12.5,
    "lon": -122.4194,
    "lat": 37.7749,
    "course": 175,
    "heading": 180,
    "timestamp": "2025-12-05T10:30:00",
    "ship_id": "123456"
  }
]

6.get_port_calls

获取船只的港口停靠历史记录，包括到达和离开。

参数：

vessel_id （字符串，必填）：船舶标识符
id_type （字符串，必填）：标识符类型- mmsi, imo，或 shipid
days （数字，可选）：历史天数（1-365，默认值：30）

例子：

{
  "vessel_id": "9123456",
  "id_type": "imo",
  "days": 90
}

答复：

[
  {
    "mmsi": "371234000",
    "imo": "9123456",
    "ship_name": "EXAMPLE VESSEL",
    "port_id": 3489,
    "port_name": "SAN FRANCISCO",
    "country_code": "US",
    "arrival": "2025-12-01T08:00:00",
    "departure": "2025-12-03T14:00:00",
    "time_at_port": 54,
    "last_port_id": 2985,
    "last_port_name": "SEATTLE",
    "next_port_id": 1234,
    "next_port_name": "LOS ANGELES"
  }
]

7.get_vessel_ta

通过距离和速度计算获得估计到达时间。

参数：

vessel_id （字符串，必填）：船舶标识符
id_type （字符串，必填）：标识符类型- mmsi, imo，或 shipid

例子：

{
  "vessel_id": "371234000",
  "id_type": "mmsi"
}

答复：

{
  "mmsi": "371234000",
  "imo": "9123456",
  "ship_name": "EXAMPLE VESSEL",
  "destination_port": "LOS ANGELES",
  "port_id": 1234,
  "eta": "2025-12-06T14:00:00",
  "distance": 245.5,
  "remaining_time": 18,
  "average_speed": 13.6,
  "current_speed": 12.5
}

8.获取_容器_事件

获取船只最近事件和活动的时间表。

参数：

vessel_id （字符串，必填）：船舶标识符
id_type （字符串，必填）：标识符类型- mmsi, imo，或 shipid
days （数字，可选）：历史天数（1-90，默认值：7）

例子：

{
  "vessel_id": "371234000",
  "id_type": "mmsi",
  "days": 14
}

答复：

[
  {
    "mmsi": "371234000",
    "imo": "9123456",
    "ship_name": "EXAMPLE VESSEL",
    "event_type": "PORT_ARRIVAL",
    "event_time": "2025-12-01T08:00:00",
    "port_id": 3489,
    "port_name": "SAN FRANCISCO",
    "location": "San Francisco Bay",
    "description": "Vessel arrived at port"
  }
]

港口情报工具

9.获取端口详细信息

获取特定端口的详细信息。

参数：

port_id （数字，必填）：唯一端口标识符

例子：

{
  "port_id": 3489
}

答复：

{
  "port_id": 3489,
  "port_name": "SAN FRANCISCO",
  "country_code": "US",
  "country": "United States",
  "lat": 37.7749,
  "lon": -122.4194,
  "map_url": "https://marinetraffic.com/port/3489",
  "vessel_count": 42
}

10.搜索端口

按名称或国家搜索港口。

参数：

query （字符串，必填）：搜索查询（端口名或国家名称）
search_type （字符串，必填）：搜索类型- name 或 country

例子：

{
  "query": "Singapore",
  "search_type": "name"
}

答复：

[
  {
    "port_id": 3369,
    "port_name": "SINGAPORE",
    "country_code": "SG",
    "country": "Singapore",
    "lat": 1.2652,
    "lon": 103.8516,
    "vessel_count": 156
  }
]

接近和发现工具

11.获取earby_vessels

查找特定位置半径内的所有船只。

参数：

latitude （数字，必填）：中心点纬度
longitude （数字，必填）：中心点经度
radius （数字，可选）：搜索半径，单位为海里（0.1-100，默认值：5）

例子：

{
  "latitude": 37.7749,
  "longitude": -122.4194,
  "radius": 10
}

答复：

[
  {
    "mmsi": "371234000",
    "imo": "9123456",
    "ship_name": "EXAMPLE VESSEL",
    "ship_type": "Cargo",
    "lat": 37.7850,
    "lon": -122.4100,
    "distance": 1.2,
    "speed": 8.5,
    "heading": 175,
    "status": "Under way using engine",
    "timestamp": "2025-12-05T10:30:00"
  }
]

项目结构

marine-traffic-mcp/
├── client/              # Marine Traffic API client
│   ├── client.go       # HTTP client and API methods
│   └── types.go        # Data type definitions
├── config/             # Configuration management
│   └── config.go       # Environment variable handling
├── server/             # MCP server implementation
│   └── server.go       # MCP protocol handlers
├── main.go             # Application entry point
├── go.mod              # Go module definition
├── .env.example        # Example environment configuration
├── .gitignore         # Git ignore rules
└── README.md          # This file

建筑

服务器遵循干净、可扩展的架构：

配置层 (config/)：处理环境变量加载和验证
客户端层 (client/)：封装所有海上交通API交互
服务器层 (server/)：实现MCP协议和工具处理程序
主入口点 (main.go)：将所有东西连接在一起

可扩展性

要添加新工具，请执行以下操作：

将新的API方法添加到 client/client.go
在中定义响应类型 client/types.go
在中注册该工具 server/server.go 使用 registerTools()
按照现有处理程序中的模式实现处理程序函数

错误处理

服务器实现了全面的错误处理：

配置错误：已记录并立即退出
API错误：作为MCP错误响应返回，并包含详细消息
网络错误：用上下文包装并返回给客户端
验证错误：在MCP工具处理程序级别检查

安全

API密钥管理

API键仅从环境变量加载
切勿在源代码中硬编码API密钥
这 .env 通过以下方式将文件排除在版本控制之外 .gitignore
密钥通过HTTP查询参数安全传递（建议使用HTTPS）

最佳实践

始终使用HTTPS进行API通信（默认）
将API密钥存储在 .env 文件或安全环境变量存储
永不承诺 .env 文件到版本控制
定期旋转API键
使用具有最低权限的受限API密钥

发展

在调试模式下运行

启用调试模式以查看详细的请求/响应信息：

DEBUG=true ./marine-traffic-mcp

手动测试工具

您可以使用任何MCP客户端或Claude Desktop应用程序测试这些工具。

API费率限制

API海上交通强制执行费率限制。典型的限制是：

每分钟200个请求

超过此限制将导致HTTP 429（太多请求）响应。在生产使用中实施适当的限速。

许可证

[您的许可证在这里]

贡献

欢迎投稿！请随时提交拉取请求。

支持

关于以下问题：

此MCP服务器：在此存储库中打开一个问题
海上交通API：联系方式海上交通支援
MCP协议：参观 MCP文件

致谢

内置于 mcp走
海上交通数据由 MarineTraffic.com

使用说明

海上交通MCP服务器

特性

核心船舶跟踪

历史和航行数据

港口情报

邻近与发现

先决条件

安装

配置

环境变量

用法

运行服务器

MCP工具

核心容器跟踪工具

1.获取_容器_位置

2.获取详细信息

3.搜索_容器

4.获取_容器_区域

历史和航行跟踪工具

5.获取历史轨迹

6.get_port_calls

7.get_vessel_ta

8.获取_容器_事件

港口情报工具

9.获取端口详细信息

10.搜索端口

接近和发现工具

11.获取earby_vessels

项目结构

建筑

可扩展性

错误处理

安全

API密钥管理

最佳实践

发展

在调试模式下运行

手动测试工具

API费率限制

许可证

贡献

支持

致谢

相关 MCP

互联网流量洞察与网络分析MCP服务

实时金融新闻分析服务

金融数据服务

股票数据服务

热点新闻MCP服务器

区块链监控服务器