HelloWorld
登录
w

wows-ship-mcp

games-and-gamificationsearchapi-testing

176 查看 · 2026-07-07 更新

World of Warships Ship Data MCP Tool

重要声明

本工具仅供学习和研究目的使用

  • 本工具使用Wargaming.net公开API获取战舰世界舰船数据
  • 请严格遵守Wargaming.net开发者条款
  • 禁止将本工具用于商业用途或违反游戏服务条款的行为
  • 使用本工具即表示您同意承担相应的法律责任

使用限制

  • 非商业使用: 本工具仅限个人学习和非商业研究使用
  • API配额: 请合理使用API避免过度请求导致配额耗尽
  • 数据准确性: API数据可能存在延迟或不准确请以游戏内实际数据为准
  • 服务可用性: Wargaming API服务可能因维护或其他原因暂时不可用

数据使用声明

本工具通过Wargaming.net官方API获取数据所有舰船数据版权归Wargaming.net所有用户在使用本工具时应

  1. 遵守Wargaming.net的使用条款和隐私政策
  2. 不得将获取的数据用于商业目的
  3. 不得恶意请求或滥用API服务
  4. 尊重游戏开发商的知识产权

一个强大的MCPModel Context Protocol工具用于获取战舰世界游戏中的舰船数据通过Wargaming.net官方API提供准确实时的舰船信息

功能特性

  • 舰船搜索: 根据舰船名称快速搜索
  • 详细信息: 获取舰船的完整技术参数和历史信息
  • 舰船对比: 同时对比多艘舰船的性能参数
  • 多语言支持: 支持多种语言的舰船信息
  • 按国家筛选: 获取特定国家的所有舰船
  • 按类型筛选: 按驱逐舰巡洋舰战列舰航母分类
  • 按等级筛选: 获取特定等级的舰船信息
  • 智能缓存: 自动缓存API响应提高性能
  • 错误处理: 完善的错误处理和重试机制

安装和配置

环境变量设置

  1. 复制环境变量模板:

    cp .env.example .env

  2. 编辑 .env 文件添加您的 Wargaming API 密钥:

    WARGAMING_API_KEY=your_actual_api_key_here
WOWS_REALM=asia
WOWS_LANGUAGE=zh-cn

  3. 设置系统环境变量 (推荐):

    Windows:

    setx WARGAMING_API_KEY "your_actual_api_key_here"

    macOS/Linux:

    export WARGAMING_API_KEY="your_actual_api_key_here"
# 添加到 ~/.bashrc 或 ~/.zshrc 以持久化
echo 'export WARGAMING_API_KEY="your_actual_api_key_here"' >> ~/.bashrc

Claude Desktop 配置

在 Claude Desktop 配置文件中添加以下内容:

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

{
  "mcpServers": {
    "wows-ship-mcp": {
      "command": "python",
      "args": ["path/to/wows-ship-mcp/src/server.py"],
      "env": {
        "WARGAMING_API_KEY": "${WARGAMING_API_KEY}"
      }
    }
  }
}

重要: 将 path/to/wows-ship-mcp 替换为项目的实际绝对路径

安全注意事项

  • 使用环境变量存储 API 密钥
  • .env 文件已被 git 忽略不会被推送到远程仓库
  • claude_desktop_config.json 也被忽略以防止意外暴露密钥
  • 永远不要将真实的 API 密钥提交到版本控制系统

故障排除

常见问题

  1. API密钥无效

    • 检查环境变量WARGAMING_API_KEY是否正确设置
    • 确认API密钥在Wargaming开发者门户中有效

  2. 网络连接问题

    • 检查网络连接
    • 确认防火墙没有阻止API请求

  3. 缓存问题

    • 使用cleanup_cache工具清理过期缓存
    • 删除cache目录重新开始

可用工具

1. search_ships

搜索舰船

  • search_term: 舰船名称或部分名称
  • limit: 返回结果数量限制默认20
  • language: 结果语言默认en

2. get_ship_details

获取舰船详细信息

  • ship_id: 舰船ID
  • language: 结果语言默认en

3. get_ship_parameters

获取舰船战斗参数

  • ship_id: 舰船ID
  • language: 结果语言默认en

4. compare_ships

对比多艘舰船

  • ship_ids: 舰船ID列表2-5艘
  • language: 结果语言默认en

5. get_ships_by_nation

按国家获取舰船

  • nation: 国家名称
  • language: 结果语言默认en
  • limit: 返回数量限制默认50
  • offset: 分页偏移量默认0

6. get_ships_by_type

按类型获取舰船

  • ship_type: 舰船类型Destroyer/Cruiser/Battleship/AirCarrier
  • language: 结果语言默认en
  • limit: 返回数量限制默认50
  • offset: 分页偏移量默认0

7. get_ships_by_tier

按等级获取舰船

  • tier: 舰船等级1-11
  • language: 结果语言默认en
  • limit: 返回数量限制默认50
  • offset: 分页偏移量默认0

8. cleanup_cache

清理缓存

  • 清理过期的缓存条目
  • 返回清理统计信息

安装和使用

1. 克隆仓库

git clone https://github.com/amxkifir/wows-ship-mcp.git
cd wows-ship-mcp

2. 安装依赖

pip install -r requirements.txt

3. 配置Claude Desktop

在Claude Desktop配置文件中添加以下配置

{
  "mcpServers": {
    "wows-ship-mcp": {
      "command": "python",
      "args": ["/path/to/your/wows-ship-mcp/src/server.py"],
      "env": {
        "WARGAMING_API_KEY": "your_api_key_here"
      }
    }
  }
}

环境变量配置

创建.env文件或设置环境变量

# Windows
set WARGAMING_API_KEY=your_api_key_here

# Linux/Mac
export WARGAMING_API_KEY=your_api_key_here

JSON配置方式

也可以使用JSON配置文件config.json

{
  "api_key": "your_api_key_here",
  "language": "en",
  "cache_ttl": 3600,
  "max_retries": 3,
  "request_timeout": 30
}

传统方式

如果您使用传统的MCP服务器配置请在Claude Desktop配置中添加

{
  "mcpServers": {
    "wows-ship-mcp": {
      "command": "python",
      "args": ["/path/to/your/wows-ship-mcp/src/server.py"],
      "env": {
        "WARGAMING_API_KEY": "your_api_key_here"
      }
    }
  }
}

获取API密钥

  1. 访问Wargaming开发者门户
  2. 注册或登录您的账户
  3. 创建新的应用程序
  4. 获取您的API密钥

申请API密钥时请注意

  • 详细说明您的使用目的学习研究等
  • 确保用途符合Wargaming开发者条款
  • 避免提及任何商业用途
  • 说明您将遵守API使用限制和条款

使用方法

作为MCP服务器

配置完成后在Claude Desktop中即可使用所有工具例如

  • "搜索大和号战列舰"
  • "获取俾斯麦号的详细参数"
  • "对比衣阿华和大和的性能"
  • "显示所有美国战列舰"

可用工具

  1. search_ships: 搜索舰船
  2. get_ship_details: 获取舰船详细信息
  3. get_ship_parameters: 获取舰船战斗参数
  4. compare_ships: 对比多艘舰船
  5. get_ships_by_nation: 按国家获取舰船
  6. get_ships_by_type: 按类型获取舰船
  7. get_ships_by_tier: 按等级获取舰船
  8. cleanup_cache: 清理缓存

支持的语言

  • en - English (默认)
  • ru -
  • pl - Polski
  • de - Deutsch
  • fr - Franais
  • es - Espaol
  • zh-cn - 简体中文
  • zh-tw - 繁體中文
  • tr - Trke
  • cs - etina
  • th -
  • vi - Ting Vit
  • ko -
  • ja - 日本語

支持的国家

  • usa - 美国
  • japan - 日本
  • ussr - 苏联
  • germany - 德国
  • uk - 英国
  • france - 法国
  • italy - 意大利
  • pan_asia - 泛亚
  • commonwealth - 英联邦
  • pan_america - 泛美
  • netherlands - 荷兰
  • spain - 西班牙

支持的舰船类型

  • Destroyer - 驱逐舰
  • Cruiser - 巡洋舰
  • Battleship - 战列舰
  • AirCarrier - 航空母舰

配置

环境变量

  • WARGAMING_API_KEY: Wargaming API密钥必需
  • DEFAULT_LANGUAGE: 默认语言可选默认为'en'
  • CACHE_TTL: 缓存生存时间秒可选默认3600
  • MAX_RETRIES: 最大重试次数可选默认3
  • REQUEST_TIMEOUT: 请求超时时间秒可选默认30

API配置

工具会自动处理API限制和重试逻辑

  • 自动重试失败的请求
  • 智能缓存减少API调用
  • 请求节流避免超出限制

缓存管理

  • 自动缓存API响应
  • 可配置的缓存生存时间
  • 使用cleanup_cache工具清理过期缓存

项目结构

wows-ship-mcp/
 src/
    server.py          # 主服务器文件
    api_client.py      # API客户端
    cache.py           # 缓存管理
    config.py          # 配置管理
    tools.py           # 工具实现
    prompts.py         # 提示词配置
 cache/                 # 缓存目录
 requirements.txt       # Python依赖
 pyproject.toml        # 项目配置
 README.md             # 项目说明
 main.py               # 入口文件

错误处理

工具包含完善的错误处理机制

  • API错误: 自动重试和错误报告
  • 网络错误: 连接超时和重试逻辑
  • 数据验证: 输入参数验证
  • 缓存错误: 缓存失败时的降级处理

性能优化

  • 智能缓存: 减少重复API调用
  • 异步处理: 提高并发性能
  • 请求节流: 避免API限制
  • 数据压缩: 优化缓存存储

贡献

欢迎提交Issue和Pull Request来改进这个工具

许可证

MIT License - 详见LICENSE文件

免责声明

本工具仅供学习和研究目的使用使用者应当

  1. 遵守Wargaming.net的服务条款和API使用条款
  2. 不将本工具用于任何商业目的
  3. 尊重游戏开发商的知识产权
  4. 合理使用API避免过度请求

作者不对使用本工具可能产生的任何后果承担责任

支持

如果您在使用过程中遇到问题请

  1. 查看本README的故障排除部分
  2. 检查您的API密钥和网络连接
  3. 确保遵循Wargaming开发者条款
  4. 在GitHub上提交Issue请提供详细的错误信息

重要提醒: 使用本工具时请始终遵循Wargaming.net的开发者条款和服务条款

法律声明

本工具与Wargaming.net没有官方关联战舰世界是Wargaming.net的注册商标本工具仅使用公开可用的API数据所有数据版权归Wargaming.net所有

使用本工具即表示您

  • 同意遵守所有相关的法律法规
  • 理解并接受使用风险
  • 承诺不将工具用于违法或违规目的
  • 同意在发现任何问题时及时停止使用

API参考

本工具使用以下Wargaming API端点

  • /wows/encyclopedia/ships/ - 舰船百科数据
  • /wows/encyclopedia/shipprofile/ - 舰船配置文件

更多API信息请参考Wargaming API文档

更新日志

v1.0.0

  • 初始版本发布
  • 支持基本的舰船搜索和信息获取
  • 实现缓存机制
  • 添加多语言支持
  • 完善错误处理

服务配置

[{'mcpServers': {'wows-ship-mcp': {'args': ['/path/to/your/wows-ship-mcp/src/server.py'], 'command': 'python', 'env': {'WARGAMING_API_KEY': 'your_api_key_here'}}}}, {'mcpServers': {'wows-ship-mcp': {'args': ['/path/to/your/wows-ship-mcp/src/server.py'], 'command': 'python', 'env': {'WARGAMING_API_KEY': 'your_api_key_here'}}}}]

来源