内容
# Steam MCP 服务器
[](https://www.npmjs.com/package/@praeses/steam-mcp)
[](https://opensource.org/licenses/MIT)
一个功能丰富的 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，为 AI 助手提供对 Steam 游戏库的完全访问权限。在 **Linux、macOS 和 Windows** 上运行。14 个整合工具涵盖 66 种操作 — 大多数操作无需 API 密钥即可从本地文件工作。可选的 Steam Web API 密钥可解锁在线数据，如成就、好友和完整库访问权限。
与 Claude Desktop、Claude Code 或任何 MCP 兼容的客户端配合使用。
## 功能
**询问您的 AI 助手：**
- “我有哪些已安装的游戏？”
- “搜索 ck3” → 通过缩写匹配找到 Crusader Kings III
- “Steam 使用了多少磁盘空间？” → 按游戏划分的详细磁盘空间占用情况
- “查找我可以清理的孤儿数据” → 确定残留的 compatdata/shadercache
- “这个游戏应该使用哪个 Proton 版本？”
- “安装 Hollow Knight” → 查找 appid 并告诉 Steam 安装它
- “为我随机选择一个游戏”
- “显示我的完整游戏历史记录” → 您的整个游戏库的游戏时间
- “将我的 Lutris 游戏导入为 Steam 快捷方式”
- “显示我的 Hades 成就” → 解锁状态、完成百分比、全局统计数据
- “谁现在在线？” → 好友列表，带有在线状态和当前游戏
- “我的愿望清单上有什么？”
- “显示我对 Elden Ring 的评论”
- “通关 Hollow Knight 需要多长时间？”
## 安装
### npm（推荐）
```bash
npx @praeses/steam-mcp
```
无需安装 — 只需将其添加到您的 MCP 客户端配置中（参见下文）。
### 全局安装
```bash
npm install -g @praeses/steam-mcp
```
然后使用 `steam-mcp` 作为命令代替 `npx @praeses/steam-mcp`。
### 配置 Claude Desktop
在您的 Claude Desktop 配置文件中添加：
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"steam": {
"command": "npx",
"args": ["@praeses/steam-mcp"],
"env": {
"STEAM_API_KEY": "your-key-here"
}
}
}
}
```
### 配置 Claude Code
在您的项目根目录中添加 `.mcp.json`，或添加到 `~/.claude.json` 以实现系统范围的访问：
```json
{
"mcpServers": {
"steam": {
"command": "npx",
"args": ["@praeses/steam-mcp"],
"env": {
"STEAM_API_KEY": "your-key-here"
}
}
}
}
```
> **注意：** `STEAM_API_KEY` 是可选的。大多数工具无需它即可工作。只有少数操作（成就、好友、已拥有游戏、愿望清单、个人资料）需要它。在 [steamcommunity.com/dev/apikey](https://steamcommunity.com/dev/apikey) 获取您的密钥。
### 分类筛选
要进一步减少上下文窗口的使用，请通过 `STEAM_TOOLS` 环境变量启用特定的工具类别：
```json
{
"env": {
"STEAM_TOOLS": "core,manage,compat"
}
}
```
可用类别及其工具：
| 类别 | 工具 | 描述 |
| --- | --- | --- |
| `core` | `games`, `library`, `steam_status` | 游戏浏览、库统计、Steam 状态 |
| `compat` | `proton`, `diagnostics` | Proton/Wine 兼容性、日志解析 |
| `manage` | `game_control`, `game_config`, `shortcuts` | 安装/启动/验证、启动选项、非 Steam 快捷方式 |
| `storage` | `storage` | 磁盘使用、清理、着色器缓存、云保存、备份 |
| `api` | `player`, `workshop` | 玩家资料/成就/好友、工作坊项目 |
| `market` | `deals` | 折扣检查、愿望清单、库估值 |
| `insights` | `insights` | 完成统计、时间线、年度回顾、游戏历史、导出 |
| `content` | `game_info` | 评论、新闻、媒体、HLTB、PCGamingWiki 修复 |
当未设置时，所有类别都已启用（14 个工具，约 3,200 个 tokens）。
### 先决条件
- Node.js 18+
- Steam 安装在默认位置：
- **Linux**: `~/.local/share/Steam/`
- **macOS**: `~/Library/Application Support/Steam/`
- **Windows**: `C:\Program Files (x86)\Steam\`
> Proton/Wine 工具（兼容性跟踪、前缀检查、崩溃日志）仅限 Linux。所有其他工具都跨平台。
## 工具
每个工具使用一个 `action` 参数来选择操作。14 个工具总共涵盖 66 种操作。
### `games` — 游戏发现和浏览
| 操作 | 描述 |
| --- | --- |
| `list` | 列出已安装的游戏，支持筛选、排序、分页 |
| `get` | 获取指定 appid 的完整游戏详情 |
| `search` | 智能搜索，支持缩写匹配（例如“ck3”→Crusader Kings III） |
| `compare` | 比较两个游戏 |
| `random` | 随机选择一个已安装的游戏 |
| `unplayed` | 查找您拥有但未玩过的游戏 |
### `library` — 库文件夹和统计
| 操作 | 描述 |
| --- | --- |
| `list` | 列出所有 Steam 库文件夹，包含大小和可用空间 |
| `stats` | 聚合统计：总游戏数、游戏时间、磁盘占用 |
### `steam_status` — Steam 客户端状态
| 操作 | 描述 |
| --- | --- |
| `status` | 检查 Steam 是否正在运行 |
| `queue` | 查看当前下载队列 |
| `progress` | 检查游戏的下载进度 |
### `proton` — Proton/Wine 兼容性（Linux）
| 操作 | 描述 |
| --- | --- |
| `list_games` | 列出使用 Proton/Wine 的所有游戏，包含版本和前缀大小 |
| `info` | 获取指定游戏的兼容性详情 |
| `versions` | 列出已安装的 Proton 版本及其使用情况 |
| `db_rating` | 获取 ProtonDB 社区评分 |
| `recommend` | 为游戏推荐 Proton 版本 |
| `prefix` | 检查 Wine/Proton 前缀（Windows 版本、文件数量、大小） |
| `crash_logs` | 查找和读取崩溃转储和日志 |
### `storage` — 磁盘管理
| 操作 | 描述 |
| --- | --- |
| `disk_report` | 按游戏划分的磁盘占用情况（安装 + 兼容性数据 + 着色器缓存 + 工作坊） |
| `orphaned` | 查找未安装游戏的残留数据 |
| `cleanup` | 获取清理建议和空间节省 |
| `shader_cache` | 指定游戏的着色器缓存大小 |
| `shader_stats` | 所有游戏的着色器缓存概览 |
| `saves_list` | 列出每个游戏的本地云保存数据 |
| `saves_stats` | 云保存聚合统计 |
| `backup` | 将云保存备份到目录 |
### `game_control` — 游戏操作
| 操作 | 描述 |
| --- | --- |
| `install` | 通过 Steam 安装游戏 |
| `uninstall` | 卸载游戏 |
| `launch` | 启动游戏 |
| `verify` | 验证游戏文件完整性 |
| `move` | 将游戏移动到另一个库文件夹 |
| `store_page` | 打开 Steam 商店页面 |
### `game_config` — 配置和调整
| 操作 | 描述 |
| --- | --- |
| `get_launch_opts` | 读取当前启动选项 |
| `set_launch_opts` | 设置启动选项 |
| `presets` | 列出/应用启动选项预设（MangoHud、GameMode、Vulkan 等） |
| `mangohud` | 显示、设置或重置 MangoHud 配置 |
| `steam_settings` | 查看 Steam 客户端设置 |
### `player` — 玩家数据（大多数操作需要 API 密钥）
| 操作 | 描述 |
| --- | --- |
| `summary` | 玩家资料，包含在线状态和账户信息 |
| `level` | Steam 等级、经验值和徽章 |
| `bans` | VAC 和游戏封禁状态 |
| `friends` | 好友列表，包含在线状态和当前游戏 |
| `achievements` | 按游戏划分的成就解锁状态 |
| `global_achievements` | 全球成就解锁百分比 |
| `schema` | 游戏的成就和统计定义 |
| `owned` | 完整的已拥有游戏列表，包含游戏时间 |
| `recent` | 最近玩过的游戏 |
### `workshop` — Steam 工作坊
| 操作 | 描述 |
| --- | --- |
| `list` | 列出指定游戏的已安装工作坊项目 |
| `stats` | 所有游戏的工作坊统计 |
| `search` | 搜索 Steam 工作坊 |
### `shortcuts` — 非 Steam 游戏快捷方式
| 操作 | 描述 |
| --- | --- |
| `list` | 列出所有非 Steam 快捷方式 |
| `add` | 添加新的快捷方式 |
| `remove` | 删除快捷方式 |
| `import_lutris` | 从 Lutris 导入游戏 |
### `deals` — 定价和愿望清单
| 操作 | 描述 |
| --- | --- |
| `check_sale` | 检查游戏是否正在打折 |
| `wishlist_deals` | 查找愿望清单上的打折游戏 |
| `wishlist` | 查看完整的愿望清单，包含价格和评论 |
| `library_value` | 估算整个游戏库的价值 |
### `insights` — 分析和历史
| 操作 | 描述 |
| --- | --- |
| `completion` | 顶级游戏的成就完成率 |
| `timeline` | 按月划分的游戏活动 |
| `year_review` | 年度游戏回顾 |
| `play_history` | 完整的游戏时间历史（已安装和未安装游戏） |
| `export` | 将游戏库数据导出为 JSON 或 CSV |
### `game_info` — 游戏内容和元数据
| 操作 | 描述 |
| --- | --- |
| `reviews` | 用户评论和评分 |
| `news` | 最新新闻文章 |
| `media` | 游戏艺术作品网址和本地覆盖 |
| `hltb` | HowLongToBeat 完成时间估计 |
| `pcgamingwiki` | PCGamingWiki 修复和调整 |
### `diagnostics` — 日志解析
| 操作 | 描述 |
| --- | --- |
| `compat_log` | 解析 Proton/Wine 兼容性日志 |
| `shader_log` | 解析着色器编译日志 |
## 关键亮点
- **最小上下文占用** — 14 个工具，约 3,200 个 tokens（低于 v1 的 66 个工具 / 约 8,000 个 tokens）
- **跨平台** — Linux、macOS 和 Windows（Proton 工具仅限 Linux）
- **大多数操作无需 API 密钥** — 直接从 Steam 的本地文件读取
- **智能搜索** — “ck3” 找到 “Crusader Kings III”，“ror2” 找到 “Risk of Rain 2”
- **完整的游戏历史记录** — 您玩过的每个游戏的游戏时间，而不仅仅是已安装的游戏
- **存储分析** — 显示磁盘空间的确切占用情况（安装 + 兼容性数据 + 着色器缓存 + 工作坊）
- **孤儿检测** — 查找 GB 级别的未安装游戏残留数据
- **多库支持** — 支持多个 Steam 库文件夹，包括外部驱动器
- **类别筛选** — 通过 `STEAM_TOOLS` 环境变量启用您需要的工具组
- **自定义 VDF 解析器** — 文本和二进制格式，无外部依赖
## 开发
### 从源代码安装
```bash
git clone https://github.com/Praeses0/steam-mcp.git
cd steam-mcp
npm install
npm run build
```
### 命令
```bash
npm run dev # 使用 tsx 运行（自动重新加载）
npm run build # 编译 TypeScript
npm test # 运行测试
```
## 架构
```
src/
├── index.ts # 服务器入口，基于类别的工具注册
├── vdf/
│ ├── parser.ts # 文本 VDF 递归下降解析器 + 序列化器
│ ├── binary-parser.ts # 二进制 VDF 解析器（shortcuts.vdf）
│ ├── binary-writer.ts # 二进制 VDF 编写器（快捷方式管理）
│ └── types.ts # VdfValue, VdfObject 类型
├── steam/
│ ├── paths.ts # 跨平台 Steam 目录解析，用户检测
│ ├── manifests.ts # 应用清单读取，mtime 缓存
│ ├── library.ts # 库文件夹操作 + 磁盘信息
│ ├── userdata.ts # localconfig.vdf 读取/写入
│ ├── compat.ts # Proton/Wine 兼容性跟踪
│ ├── workshop.ts # 工作坊清单读取
│ ├── shortcuts.ts # 二进制 shortcuts.vdf 读取/写入
│ ├── api.ts # Steam Web API 客户端
│ ├── api-types.ts # 共享 API 响应类型
│ ├── wishlist.ts # 愿望清单数据获取
│ ├── logs.ts # Steam 日志解析
│ └── types.ts # 领域类型
├── tools/ # 14 个整合的 MCP 工具（每个工具一个文件）
└── util/
├── format.ts # formatBytes, formatPlaytime, formatTimestamp
├── cache.ts # FileCache<T>，带有 mtime 失效
└── fs.ts # 共享文件系统实用程序
```
## 许可证
[MIT](LICENSE)
