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. 尊重游戏开发商的知识产权

一个强大的MCP（Model 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 - Français
• es - Español
• zh-cn - 简体中文
• zh-tw - 繁體中文
• tr - Türkçe
• cs - Čeština
• th - ไทย
• vi - Tiếng Việt
• 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

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