Datalastic MCP 服务器
数据弹性海洋自动识别系统数据API的MCP（模型上下文协议）服务器。该服务器使像Claude这样的AI助手能够通过数据弹性API访问实时船舶追踪、港口信息和海洋数据。
📖 文档：
- 新用户： 从……开始 QUICK_START.md 翻译为中文是：“快速入门指南.md” 或者 “快速开始指南.md” （5分钟）
- 完整指南： 看 用户指南.md （综合的）
特点/功能
核心功能
- 船舶追踪获取船舶的实时位置、速度、航向和目的地
- 船舶历史访问船舶的历史位置数据（自2021年8月起）
- 船舶信息访问详细的船舶规格和技术数据
- 区域搜索查找地理半径范围内的所有船只
- 港口搜索按名称、类型、位置或国家查找港口
- 船队追踪同时监控多艘船只（最多100艘）
高级功能
- MCP Resources（公司名，可译为）：MCP资源公司使用自定义URI方案订阅实时船舶数据
- 智能缓存自动响应缓存，支持可配置的TTL（减少约70%的API调用）
- 速率限制追踪使用内置的请求计数功能监控您的API使用情况
- 服务器统计查看缓存命中率和API使用指标
- 全面测试完整的测试套件，包含24+个测试用例（100%通过）
安装
先决条件
- Python 3.10 或更高版本
- 一个Datalastic API密钥（可在https://datalastic.com/获取）
设置
- 安装依赖项：
pip install mcp httpx pydantic或者如果使用仓库：
cd /path/to/datalastic-mcp
pip install -e .- 以两种方式之一设置您的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，或者imoidentifier_value标识符值（例如，MMSI（海上移动服务识别码）"566093000"）detailed（可选）设置为true用于增强数据，包括预计到达时间（ETA）、实际到达时间（ATD）、吃水深度
示例查询：
- “MMSI为566093000的船舶在哪里？”
- “获取IMO编号为9525338的船舶的详细位置信息”
- “显示MAERSK CHENNAI的当前位置”
2. 获取船舶信息
获取船舶的详细规格和静态信息。
参数：
identifier_type标识符类型 -uuid，mmsi，或者imoidentifier_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或者imoidentifier_value标识符值days（可选）历史天数（例如。，5（过去5天）from_date（可选）开始日期，格式为YYYY-MM-DDto_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:/// - 示例：
- vessel://mmsi/566093000 - vessel://imo/9525338 - vessel://uuid/b8625b67-7142-cfd1-7b85-595cebfe4191
area:// URI 翻译为中文是：“区域:// 统一资源标识符（URI）”
监控特定地理区域内的船舶：
- 格式：
area://// - 示例：
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以及它是如何工作的 - 所有7种工具均附有示例说明 - Claude桌面版的逐步设置指南 - 使用示例和故障排除 - 如果你是新手，请从这里开始！
- README.md（文件名，可译为“读我”或保持原样，因其为常见标记文件名） (此文件) - 开发者快速参考指南
- 功能概述和API端点 - 安装与配置 - 工具参数及示例
支持
对于以下问题：
- 这个MCP服务器在这个仓库中打开一个问题（或议题）
- Datalastic API请访问 https://datalastic.com/ 联系 Datalastic 支持团队
- MCP协议请参阅 https://modelcontextprotocol.io/