Skip to main content
Glama
garrettXu

Shipxy MCP Server

by garrettXu
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

shipxy-api-mcp

Shipxy MCP Server 是一个完全兼容 MCP 协议的开源海事场景位置服务（LBS）解决方案，为开发者和 AI 智能体提供全面的船舶与港口 API 及工具。它可无缝集成实时船舶数据、航线规划、气象、潮汐等多种能力到您的应用中。

🚀 项目简介

Shipxy MCP Server 让您的应用、LLM 和智能体具备先进的海事数据与地理空间智能，包括：

  • 船舶信息与跟踪： 实时船舶位置、静态信息、船队与区域查询。

  • 港口与泊位数据： 全球港口检索、靠泊/锚地/ETA 查询、靠港记录。

  • 航线规划： 点到点、港到港航线规划。

  • 气象与潮汐： 海洋气象、台风、潮汐站数据。

  • 丰富的海事API： 船籍、档案、搭靠事件等。

所有 API 均遵循 MCP 协议，可被任何 MCP 兼容的客户端、LLM 或智能体平台调用。

Related MCP server: VesselAPI MCP Server

🛠️ 主要特性

  • 完整 MCP 协议支持： 可无缝集成到任何 MCP 兼容的智能体、LLM 或平台。

  • 全面的海事数据： 船舶、港口、航线、气象、潮汐等。

  • 实时与历史数据： 实时船舶跟踪、航次历史、事件记录。

  • 开源易扩展： MIT 协议，便于自定义和扩展。

⚡ 快速开始

1. 获取 API Key

请在 船讯网开放平台 注册并创建服务端 API Key。 注意： 所有请求均需 API Key。

2. 安装依赖

正式发布到 PyPI 后可直接安装：

pipx install mcp-shipxy-api

或安装到已有虚拟环境：

pip install mcp-shipxy-api

本地源码开发：

pip install -r requirements.txt

3. 配置

在项目根目录创建 .env 文件：

SHIPXY_API_KEY=你的_api_key

4. 启动服务

直接使用船讯网托管 SSE 服务

如果你不想在本地运行源码，可以直接连接船讯网提供的 MCP SSE 服务：

https://mcp.shipxy.com/sse

Cursor、Cherry Studio 或其他支持 SSE 的 MCP 客户端可按下面填写：

名称：shipxy
描述：Shipxy MCP 海事数据服务
URL：https://mcp.shipxy.com/sse
传输协议：Server-Sent Events (SSE)
认证方式：Bearer Token
Bearer Token：你的 Shipxy API Key
超时时间：30000

Cursor JSON 配置示例：

{
  "mcpServers": {
    "shipxy": {
      "url": "https://mcp.shipxy.com/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer 你的 Shipxy API Key"
      }
    }
  }
}

如果你的客户端使用 type 字段表示传输协议，也可以写成：

{
  "mcpServers": {
    "shipxy": {
      "type": "sse",
      "url": "https://mcp.shipxy.com/sse",
      "headers": {
        "Authorization": "Bearer 你的 Shipxy API Key"
      }
    }
  }
}

注意：URL 必须包含 /sse；Bearer Token 填你自己的船讯网 API Key，不需要配置本地 command、args 或 .venv。

stdio 方式

推荐使用 mcp.json 配置文件，便于与 MCP CLI 及智能体平台集成。示例：

{
  "mcpServers": {
    "shipxy-api-mcp": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {
        "SHIPXY_API_KEY": "你的_api_key"
      }
    }
  }
}

也可以直接运行：

python server.py

SSE 方式

需要把服务部署成 HTTP/SSE 时，可以这样启动：

python server.py --transport sse --host 0.0.0.0 --port 18081

SSE 端点：

http://localhost:18081/sse

消息端点：

http://localhost:18081/messages/

SSE 支持两种 API Key 传入方式：

curl 'http://localhost:18081/sse?ak=你的_api_key'
curl -H 'Authorization: Bearer 你的_api_key' http://localhost:18081/sse

MCP 客户端配置 SSE 时，推荐使用 Bearer Token：

SSE URL: http://localhost:18081/sse
Authentication: Bearer Token
Token: 你的 Shipxy API Key

CLI 使用

本项目也提供跨平台 CLI，命令保持扁平结构，直接对应 MCP tool 名称，仅把下划线改成短横线：

python -m venv .venv
source .venv/bin/activate
pip install -e .

shipxy auth status
shipxy tools
shipxy schema search-ship
shipxy search-ship COSCO --max 5
shipxy get-single-ship 413211000
shipxy search-port Shanghai
shipxy plan-route-by-port CNSHA SGSIN
shipxy plan-route-by-point 113.571144,22.844316 --end-port-code CNQDG
shipxy get-weather-by-point --lng 123.58414 --lat 27.37979

Windows PowerShell 激活虚拟环境：

.\.venv\Scripts\Activate.ps1

CLI 默认输出 JSON，方便大模型和其他 Agent 调用。需要人类可读输出时可指定：

shipxy search-ship COSCO --max 5 --format table
shipxy search-ship COSCO --max 5 --format pretty
shipxy search-ship COSCO --max 5 --format ndjson

也可以通过 CLI 启动 MCP Server：

shipxy mcp start
shipxy mcp start --transport sse --host 0.0.0.0 --port 18081

stdio 方式下，Agent 和 MCP 客户端应通过 SHIPXY_API_KEY 环境变量传入 API Key：

{
  "mcpServers": {
    "shipxy": {
      "command": "shipxy",
      "args": ["mcp", "start"],
      "env": {
        "SHIPXY_API_KEY": "你的_api_key"
      }
    }
  }
}

Agent 调用建议

面向大模型和其他 Agent 调用时，建议按这个顺序使用：

  1. describe_capabilities：查看可用工具、适用场景、返回对象和常见错误。

  2. describe_object：查看返回对象字段含义，例如 VesselPosition、Port、Route。

  3. validate_tool_input：在正式调用 Shipxy 前预校验参数，获取字段级修复建议。

  4. 调用具体业务工具，例如 search_ship、get_single_ship、plan_route_by_port。

所有业务工具返回都包含 ok、tool、returns、capability_ref、object_refs。失败时返回结构化 error，包括错误类型、消息、详情和可执行修复建议。

🧩 支持的API

工具名称

说明

describe_capabilities

查询工具能力、返回对象、错误和调用建议

describe_object

查询返回对象 schema 和字段含义

validate_tool_input

预校验工具入参并返回修复建议

search_ship

按 MMSI、IMO、船名、呼号模糊查询船舶

get_single_ship

查询单船实时信息（MMSI）

get_many_ship

查询多船实时信息（MMSI列表）

get_fleet_ship

查询船队下所有船舶

get_surrounding_ship

查询指定船舶10海里内的周边船舶

get_area_ship

查询指定区域内的船舶

get_ship_registry

查询船舶国籍/船籍信息

search_ship_particular

按 MMSI/IMO/呼号/船名查船舶档案

search_port

按名称或五位码模糊查询港口

get_berth_ships

查询港口当前靠泊船舶

get_anchor_ships

查询港口当前锚地船舶

get_eta_ships

查询未来预计到港船舶

get_ship_track

查询船舶历史轨迹点

search_ship_approach

查询船舶搭靠事件

get_port_of_call_by_ship

查询船舶靠港记录

get_port_of_call_by_ship_port

查询船舶在指定港口的靠港记录

get_port_of_call_by_port

查询港口靠港记录

plan_route_by_point

点到点/点到港航线规划

plan_route_by_port

港到港航线规划

get_single_eta_precise

查询船舶ETA及航程信息

get_weather_by_point

按坐标查询海洋气象

get_weather

按区域查询海洋气象

get_all_typhoon

查询近年台风列表

get_single_typhoon

查询指定台风详情

get_tides

查询潮汐观测站列表

get_tide_data

查询指定潮汐站潮汐数据

get_global_tides

查询全球潮汐观测站列表

get_global_tide_data

查询指定全球潮汐站潮汐数据

current_weather

查询全球实时大气与海洋气象

future_weather

查询全球未来大气与海洋气象预报

history_weather

查询指定坐标和时间范围的历史气象

get_nav_warning

查询中国海事局航行警告

🌍 应用场景

  • 航运物流与船队管理

  • 船舶跟踪与监控

  • 港口运营与ETA预测

  • 智能航运与航线优化

  • 海洋气象与安全应用

📦 项目结构

.
├── server.py           # MCP服务入口
├── ship_service.py     # 船讯网API集成与业务逻辑
├── tool_registry.py    # CLI/MCP工具注册表
├── domain_catalog.py   # 能力目录、返回对象schema、字段解释
├── validation.py       # 入参预校验与修复建议
├── requirements.txt    # Python依赖
├── pyproject.toml      # 项目元数据
└── README.md           # 本文件

📄 许可证

MIT © shipxy-api-mcp 贡献者

📞 联系方式

如需了解更多或商务合作，请联系：

电话： 400-010-8558 / 010-8286 8599

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/garrettXu/mcp-shipxy-api'

If you have feedback or need assistance with the MCP directory API, please join our Discord server