# shipxy-api-mcp **Shipxy MCP Server** 是一个完全兼容 MCP 协议的开源海事场景位置服务（LBS）解决方案，为开发者和 AI 智能体提供全面的船舶与港口 API 及工具。它可无缝集成实时船舶数据、航线规划、气象、潮汐等多种能力到您的应用中。 ## 🚀 项目简介 **Shipxy MCP Server** 让您的应用、LLM 和智能体具备先进的海事数据与地理空间智能，包括： - **船舶信息与跟踪：** 实时船舶位置、静态信息、船队与区域查询。 - **港口与泊位数据：** 全球港口检索、靠泊/锚地/ETA 查询、靠港记录。 - **航线规划：** 点到点、港到港航线规划。 - **气象与潮汐：** 海洋气象、台风、潮汐站数据。 - **丰富的海事API：** 船籍、档案、搭靠事件等。 所有 API 均遵循 MCP 协议，可被任何 MCP 兼容的客户端、LLM 或智能体平台调用。 ## 🛠️ 主要特性 - **完整 MCP 协议支持：** 可无缝集成到任何 MCP 兼容的智能体、LLM 或平台。 - **全面的海事数据：** 船舶、港口、航线、气象、潮汐等。 - **实时与历史数据：** 实时船舶跟踪、航次历史、事件记录。 - **开源易扩展：** MIT 协议，便于自定义和扩展。 ## ⚡ 快速开始 ### 1. 获取 API Key 请在 [船讯网开放平台](https://api.shipxy.com/v3/console/overview) 注册并创建服务端 API Key。 **注意：** 所有请求均需 API Key。 ### 2. 安装依赖 正式发布到 PyPI 后可直接安装： ```bash pipx install mcp-shipxy-api ``` 或安装到已有虚拟环境： ```bash pip install mcp-shipxy-api ``` 本地源码开发： ```bash pip install -r requirements.txt ``` ### 3. 配置 在项目根目录创建 `.env` 文件： ``` SHIPXY_API_KEY=你的_api_key ``` ### 4. 启动服务 #### 直接使用船讯网托管 SSE 服务 如果你不想在本地运行源码，可以直接连接船讯网提供的 MCP SSE 服务： ```text https://mcp.shipxy.com/sse ``` Cursor、Cherry Studio 或其他支持 SSE 的 MCP 客户端可按下面填写： ```text 名称：shipxy 描述：Shipxy MCP 海事数据服务 URL：https://mcp.shipxy.com/sse 传输协议：Server-Sent Events (SSE) 认证方式：Bearer Token Bearer Token：你的 Shipxy API Key 超时时间：30000 ``` Cursor JSON 配置示例： ```json { "mcpServers": { "shipxy": { "url": "https://mcp.shipxy.com/sse", "transport": "sse", "headers": { "Authorization": "Bearer 你的 Shipxy API Key" } } } } ``` 如果你的客户端使用 `type` 字段表示传输协议，也可以写成： ```json { "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 及智能体平台集成。示例： ```json { "mcpServers": { "shipxy-api-mcp": { "command": "python", "args": ["/path/to/your/server.py"], "env": { "SHIPXY_API_KEY": "你的_api_key" } } } } ``` 也可以直接运行： ```bash python server.py ``` #### SSE 方式 需要把服务部署成 HTTP/SSE 时，可以这样启动： ```bash python server.py --transport sse --host 0.0.0.0 --port 18081 ``` SSE 端点： ```text http://localhost:18081/sse ``` 消息端点： ```text http://localhost:18081/messages/ ``` SSE 支持两种 API Key 传入方式： ```bash curl 'http://localhost:18081/sse?ak=你的_api_key' curl -H 'Authorization: Bearer 你的_api_key' http://localhost:18081/sse ``` MCP 客户端配置 SSE 时，推荐使用 Bearer Token： ```text SSE URL: http://localhost:18081/sse Authentication: Bearer Token Token: 你的 Shipxy API Key ``` ## CLI 使用 本项目也提供跨平台 CLI，命令保持扁平结构，直接对应 MCP tool 名称，仅把下划线改成短横线： ```bash 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 激活虚拟环境： ```powershell .\.venv\Scripts\Activate.ps1 ``` CLI 默认输出 JSON，方便大模型和其他 Agent 调用。需要人类可读输出时可指定： ```bash 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： ```bash shipxy mcp start shipxy mcp start --transport sse --host 0.0.0.0 --port 18081 ``` stdio 方式下，Agent 和 MCP 客户端应通过 `SHIPXY_API_KEY` 环境变量传入 API Key： ```json { "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