AI导哈

船舶数据服务

Datalastic MCP Server 是一个提供实时船舶跟踪、港口信息和海事数据的服务，通过Datalastic API为AI助手等应用提供数据支持。

  • by robderstadt
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 robderstadt/datalastic-mcp

使用说明

Datalastic MCP 服务器

数据弹性海洋自动识别系统数据API的MCP（模型上下文协议）服务器。该服务器使像Claude这样的AI助手能够通过数据弹性API访问实时船舶追踪、港口信息和海洋数据。

📖 文档：

特点/功能

核心功能

  • 船舶追踪获取船舶的实时位置、速度、航向和目的地
  • 船舶历史访问船舶的历史位置数据（自2021年8月起）
  • 船舶信息访问详细的船舶规格和技术数据
  • 区域搜索查找地理半径范围内的所有船只
  • 港口搜索按名称、类型、位置或国家查找港口
  • 船队追踪同时监控多艘船只（最多100艘）

高级功能

  • MCP Resources（公司名，可译为）：MCP资源公司使用自定义URI方案订阅实时船舶数据
  • 智能缓存自动响应缓存，支持可配置的TTL（减少约70%的API调用）
  • 速率限制追踪使用内置的请求计数功能监控您的API使用情况
  • 服务器统计查看缓存命中率和API使用指标
  • 全面测试完整的测试套件，包含24+个测试用例（100%通过）

安装

先决条件

  • Python 3.10 或更高版本
  • 一个Datalastic API密钥（可在https://datalastic.com/获取）

设置

  1. 安装依赖项：
pip install mcp httpx pydantic

或者如果使用仓库：

cd /path/to/datalastic-mcp
pip install -e .
  1. 以两种方式之一设置您的API密钥：

选项A：环境变量

export DATALASTIC_API_KEY="your-api-key-here"

选项B：文件 （建议用于开发） 创建一个名为 datalastic_api_key.txt 在项目根目录中包含您的API密钥。

用法

使用 Claude Desktop

将此配置添加到您的Claude桌面配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "datalastic": {
      "command": "python",
      "args": ["-m", "datalastic_mcp"],
      "cwd": "/Users/rob/projects/Datalastic/MCP",
      "env": {
        "DATALASTIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

注：更换 /Users/rob/projects/Datalastic/MCP 以及此项目的实际路径。

使用MCP Inspector（用于测试）

交互式测试服务器：

npx @modelcontextprotocol/inspector python -m datalastic_mcp

直接使用

直接运行服务器：

python -m datalastic_mcp

可用工具

1. 获取船舶位置

获取特定船舶的实时位置和状态。

参数：

  • identifier_type标识符类型 - uuid， mmsi，或者 imo
  • identifier_value标识符值（例如，MMSI（海上移动服务识别码） "566093000"）
  • detailed（可选）设置为 true 用于增强数据，包括预计到达时间（ETA）、实际到达时间（ATD）、吃水深度

示例查询：

  • “MMSI为566093000的船舶在哪里？”
  • “获取IMO编号为9525338的船舶的详细位置信息”
  • “显示MAERSK CHENNAI的当前位置”

2. 获取船舶信息

获取船舶的详细规格和静态信息。

参数：

  • identifier_type标识符类型 - uuid， mmsi，或者 imo
  • identifier_value标识符的值

示例查询：

  • “船籍号为IMO 9525338的船舶规格是什么？”
  • “请给我展示船籍编号为566093000的船舶的详细信息。”
  • “获取该船舶的吨位和尺寸”

3. 在区域内查找船只

查找地理坐标范围内半径内的所有船只。

参数：

  • latitude中心点纬度（例如。， 51.9225)
  • longitude中心点经度（例如。， 4.4792)
  • radius_nautical_miles搜索半径（以海里为单位，最大50）

示例查询：

  • “请显示罗特丹港（51.9225, 4.4792）25海里范围内的所有船只”
  • “在坐标40.7128, -74.0060附近10海里范围内查找船只”
  • “新加坡周边区域有哪些船只？”

4. 搜索端口

根据各种标准搜索端口。

参数：

  • name（可选）要搜索的端口名称
  • fuzzy（可选）启用模糊名称匹配（默认：false）
  • port_type（可选）按端口类型过滤
  • country_iso（可选）两位字母国家代码（例如。， "NL")
  • latitude， longitude， radius_nautical_miles（可选）地理搜索

示例查询：

  • “查找所有名为鹿特丹的港口”
  • “在荷兰搜索集装箱港口”
  • “显示坐标1.2897, 103.8501附近的港口”
  • “在新加坡寻找停泊处”

5. 跟踪多艘船舶

一次性获取多艘船舶（最多100艘）的当前状态。

参数：

  • vessels船舶标识符数组，每个标识符都带有 type 并且 value

示例查询：

  • “追踪这些船只：MMSI 566093000，IMO 9525338，以及MMSI 477123456”
  • “请向我展示我10艘船队的状况”

6. 获取船舶历史记录

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

参数：

  • identifier_type标识符的类型 - uuid， mmsi或者 imo
  • identifier_value标识符值
  • days（可选）历史天数（例如。， 5 （过去5天）
  • from_date（可选）开始日期，格式为YYYY-MM-DD
  • to_date（可选）结束日期，格式为YYYY-MM-DD

返回值：

  • 带有时间戳的历史位置信息，包括坐标、速度、航向、方向、目的地
  • 自2021年8月10日起有数据可用

注： 使用任意一个 days 或者 from_date/to_date（两者）中有一个，但不是两个。

示例查询：

  • “显示MMSI为566093000的船舶过去5天的位置历史记录”
  • “获取国际海事组织编号9525338的船舶在2025年10月1日至2025年10月15日期间的船舶历史记录”
  • “过去一周，马士基金奈号（MAERSK CHENNAI）的航线是怎样的？”

7. 获取服务器统计信息

获取服务器性能和使用统计数据。

参数： 无

返回值：

  • 缓存统计信息（命中、未命中、命中率、条目数）
  • 速率限制信息（当前小时内的请求次数，重置前剩余时间）

示例查询：

  • “给我看看服务器状态”
  • “缓存命中率是多少？”
  • “我这小时发了多少个API请求？”

MCP Resources（公司名，可译为“MCP资源公司”或根据具体语境保留原名）

服务器通过自定义URI方案暴露实时数据：

vessel:// URI（可翻译为：“vessel”协议下的统一资源标识符）

访问实时船舶数据：

  • 格式： vessel://<identifier_type>/<identifier_value>
  • 示例：
    • vessel://mmsi/566093000
    • vessel://imo/9525338
    • vessel://uuid/b8625b67-7142-cfd1-7b85-595cebfe4191

area:// URI 翻译为中文是：“区域:// 统一资源标识符（URI）”

监控特定地理区域内的船舶：

  • 格式： area://<latitude>/<longitude>/<radius>
  • 示例： area://51.9225/4.4792/10 （鹿特丹，半径10海里范围内）

注： 资源会自动使用缓存并返回详细的船舶信息。

API 使用的终端节点

服务器连接到以下Datalastic API终端节点：

  • /vessel - 基本船舶跟踪
  • /vessel_pro - 增强的船只追踪功能
  • /vessel_info - 船舶规格
  • /vessel_history - 历史位置数据
  • /vessel_bulk - 多船跟踪
  • /vessel_inradius - 基于区域的船舶搜索
  • /port_find - 港口搜索

性能与缓存

服务器包含一个智能缓存层，可大幅减少API调用：

缓存TTL（生存时间）

  • 船舶位置60秒（数据频繁变化）
  • 船舶规格5分钟（很少变化）
  • 船舶历史10分钟（历史数据不变）
  • 港口信息1小时（几乎从不变）
  • 区域搜索45秒

缓存优势

  • 减少API调用重复查询减少了约70%
  • 更快的响应缓存数据即时返回
  • 降低成本API请求越少，订阅成本越低
  • **更好的用户体验（UX）**用户响应时间更快

速率限制

服务器自动追踪API的使用情况：

  • 每小时请求计数
  • 自动计数器重置
  • 可通过以下方式获取使用统计数据 get_server_stats 工具

提示： 使用 get_server_stats 监控您的缓存性能和API使用情况。

错误处理

服务器能够优雅地处理常见错误：

  • 认证错误API密钥无效或缺失
  • 速率限制API配额已超出（自动追踪）
  • 未找到未找到船舶或港口
  • 网络错误连接超时或失败
  • 验证错误无效的参数或值

数据类型

船舶标识符

  • **UUID（通用唯一识别码）**由Datalastic分配的唯一标识符
  • **MMSI（海上移动服务识别码）**海上移动业务识别码（9位数字）
  • **国际海事组织（IMO）**国际海事组织编号

端口类型

  • 端口
  • 锚地；停泊地；美国阿拉斯加州的一个城市：安克雷奇
  • 玛丽娜
  • 海上终端
  • 庇护所；收容所
  • 拆卸场/废墟清理场
  • 运河
  • 渔港

发展

项目结构

datalastic-mcp/
├── src/
│   └── datalastic_mcp/
│       ├── __init__.py
│       ├── __main__.py
│       ├── server.py        # MCP server implementation
│       ├── api_client.py    # Datalastic API wrapper
│       └── cache.py         # Caching layer
├── tests/
│   ├── __init__.py
│   ├── test_cache.py        # Cache tests (9 tests)
│   └── test_api_client.py   # API client tests (15 tests)
├── pyproject.toml
├── README.md
└── datalastic_api_key.txt  # Your API key (gitignored)

运行测试

# Install dev dependencies
pip install pytest pytest-asyncio

# Run all tests
python3 -m pytest tests/ -v

# Run specific test file
python3 -m pytest tests/test_cache.py -v

# Run with coverage
python3 -m pytest tests/ --cov=src/datalastic_mcp

测试结果： 全部24项测试通过 ✅

  • 缓存功能：9/9项测试通过
  • API客户端：15/15项测试

API 文档

如需了解更多关于Datalastic API的信息，请访问：

  • API 参考：https://datalastic.com/api-reference/
  • 网站：https://datalastic.com/

许可证

此项目按原样提供，用于与Datalastic API一起使用。

文档

此存储库包含多个针对不同受众的文档文件：

支持

对于以下问题：

  • 这个MCP服务器在这个仓库中打开一个问题（或议题）
  • Datalastic API请访问 https://datalastic.com/ 联系 Datalastic 支持团队
  • MCP协议请参阅 https://modelcontextprotocol.io/

相关 MCP