World of Warships Ship Data MCP

World of Warships Ship Data MCP Tool

重要声明

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

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

使用限制

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

数据使用声明

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

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

一个强大的MCP（Model Context Protocol）工具，用于获取《战舰世界》游戏中的舰船数据。通过Wargaming.net官方API提供准确、实时的舰船信息。

功能特性

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

安装和配置

环境变量设置

复制环境变量模板:
cp .env.example .env
编辑 .env 文件，添加您的 Wargaming API 密钥:
WARGAMING_API_KEY=your_actual_api_key_here WOWS_REALM=asia WOWS_LANGUAGE=zh-cn
设置系统环境变量 (推荐):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 密钥提交到版本控制系统

故障排除

常见问题

API密钥无效
- 检查环境变量WARGAMING_API_KEY是否正确设置
- 确认API密钥在Wargaming开发者门户中有效
网络连接问题
- 检查网络连接
- 确认防火墙没有阻止API请求
缓存问题
- 使用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密钥

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

申请API密钥时请注意：

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

使用方法

作为MCP服务器

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

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

可用工具

search_ships: 搜索舰船
get_ship_details: 获取舰船详细信息
get_ship_parameters: 获取舰船战斗参数
compare_ships: 对比多艘舰船
get_ships_by_nation: 按国家获取舰船
get_ships_by_type: 按类型获取舰船
get_ships_by_tier: 按等级获取舰船
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文件

免责声明

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

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

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

支持

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

查看本README的故障排除部分
检查您的API密钥和网络连接
确保遵循Wargaming开发者条款
在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

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