mcp-romm 是 RomM 自托管复古游戏库管理器的 MCP 服务器，可通过任意兼容 MCP 的 AI 助手浏览和管理游戏库。
用途
为 RomM 提供 MCP 接口，使 AI 助手能够以自然语言查询和操作个人复古游戏库，覆盖资料浏览、ROM 搜索、元数据查看、存档和任务查询等场景。
主要能力
共 40 个工具：26 个只读工具，用于浏览平台、搜索 ROM、查看元数据、合集（普通、智能和虚拟）、存档、游玩活动和任务；14 个写入工具，用于管理游玩状态、游玩会话、收藏、笔记和合集。
示例查询包括：
- “RomM 中有哪些平台？”
- “搜索 Zelda 游戏”
- “显示我的待玩列表”
- “我一共有多少 ROM？”
- “最近添加了什么？”
- “显示 Super Metroid 的存档”
- “我的收藏里有什么？”
- “列出 PlayStation 的固件文件”
- “有哪些任务正在运行？”
- “注册了哪些设备？”
写入示例包括：
- “将 Chrono Trigger 标记为已完成”
- “收藏 Super Metroid”
- “加入待玩列表并评分 9”
- “创建名为 'SNES RPGs' 的合集并添加 ROM 10、11 和 12”
- “给这个 ROM 添加笔记：'第二个 Boss 有故障，多保存'”
使用方式
需要运行中的 RomM 实例（v5.0+；大多数只读工具也支持 v4.4+）以及一个已启用的 RomM 用户账号，无需管理员权限。可通过克隆安装并设置环境变量；支持添加到 Claude Code（如 .mcp.json）、Claude Desktop（如 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json）。默认使用 stdio 传输，也可作为远程 HTTP 服务托管：设置环境变量后，客户端指向该服务，例如 Claude Code。HTTP 传输没有自带认证，只能绑定到受信任网络（LAN、VPN 或 Tailscale 等覆盖网络），切勿暴露到开放互联网；注意 claude.ai 网页/移动端连接器从 Anthropic 云端发起，无法访问私有网络 URL。
认证与安全
服务器使用 OAuth2 密码授权与 RomM 认证。令牌仅申请所需的最小权限范围，包括只读范围以及 roms.user.write、collections.write 和 tasks.run；不会申请 roms.write、platforms.write、firmware.write、assets.write、users.write 或 me.write。写入工具仅修改用户自己的数据（游玩状态、收藏、笔记）和自己的合集；没有工具会编辑 ROM 文件、平台、固件、其他用户，或上传/删除存档文件。破坏性操作有明确标注：romm_delete_note 和 romm_delete_collection 会永久删除数据；romm_delete_collection 只删除分组，不删除 ROM。凭据和令牌仅保存在内存中，不写入磁盘。默认启用 TLS 证书验证（ROMM_TLS_VERIFY=true）。令牌过期时会自动重新认证并重试一次。
适用场景
适用于希望用 AI 助手以对话方式查询和管理个人 RomM 游戏库的用户，尤其适合在家庭实验室或受信任网络中部署，用于浏览平台、搜索 ROM、查看元数据、管理收藏和笔记、跟踪游玩状态等。
限制与已知问题
- 需要运行中的 RomM 实例（v5.0+；大多数只读工具支持 v4.4+）和已启用的用户账号；romm_scan_library 需要有权运行任务的账号。
- RomM 5.0 将旧 viewer/editor/admin 角色合并为 user/admin，并改用权限系统；若在 5.0 实例上出现 403，需检查账号有效权限（GET /api/permissions/me）。
- RomM 5.0.0 服务端问题：romm_filters 超时（查询形成笛卡尔积，请求挂起且服务端高 CPU 持续运行，应避免调用）；一旦存在笔记，笔记列表返回 500（创建和删除笔记正常，但 romm_rom_notes 及 romm_add_note 后的读回会报错）；无法通过 REST 触发库扫描（scan_library 标记为 manual_run: false，POST /api/tasks/run/scan_library 被拒绝；romm_scan_library 会报告此情况，扫描按计划或从 Web UI 运行）。
- 许可证为 MIT。
