PvZ MCP

通过 MCP 让 AI 游玩《植物大战僵尸》：读取游戏状态，自主决定种植位置和等待时间，再通过工具执行操作。整个过程可以不看画面、不操作鼠标。

当前版本：0.3.5，支持 Windows x64 上运行的特定 1.2.0.1073 构建。

本项目提供工具源码和安装脚本，不包含游戏文件、资源或存档。使用者需要自行准备兼容的游戏，以及支持本地 stdio MCP 的 AI 客户端。

功能

• 自动连接：自行先开游戏，MCP 自动发现并接入；无需在安装时选择游戏路径，保留当前棋盘。
• 读取局势：以 JSON 获取植物、僵尸、子弹、血量、阳光、卡牌冷却、物品和波次等状态。
• 控制节奏：暂停游戏、按指定时长推进后再次暂停，或持续运行；支持调整倍速。
• 执行操作：选择模式与关卡、选卡、按正常规则种植、拾取物品、推进戴夫对话和使用铲子；支持读取与使用传送带卡牌。
• 观战提示：显示决策计时、推进倒计时，以及 AI 的打算和操作说明。
• 桌面面板：发现与连接游戏、开始冒险、暂停 / 持续运行 / 定时推进，调整倍速和观战提示，查看彩色文字棋盘并复制局面 JSON。
• 管理进度：读取存档信息，在主菜单修改冒险进度并备份原档。
• 检查更新：MCP 启动后在后台查询本仓库 Release，默认每 24 小时检查一次，也可手动检查。

默认自动拾取阳光，使用原生声音和收集动画，不增加额外阳光。工具本身不包含自动决策策略，如何游玩由连接它的 AI 决定。

兼容性

| 游戏构建 | 状态 | 验证范围 | | --- | --- | --- | | 1.2.0.1073，下方所列 SHA-256 | 已适配 | 启动、菜单、冒险 1-4 基础操作，以及 1-5 对话、三次铲除、传送带两种坚果和完整战斗已实机验证 | | 1.0.0.1051，已检查构建 | 不支持 | 当前适配无法直接使用，可安装工具但不能启用游戏控制 | | 其他同版本构建、汉化或修改版 | 未验证 | 版本号相同也不保证兼容 | | 其他 Steam / GOTY 构建、重制版及移动版 | 未适配 | 暂不支持 |

**目前只有下列 EXE 哈希可以启用游戏控制。**安装时无需选择游戏。连接时会校验实际进程；不受支持的构建不会加载桥接。未验证不等于一定不兼容，但需要另行验证后才能启用。

e1511201ec2ae9a7e30259f04bc2ec7272badb2574a2e9b405d0e916ae5c082c

可在 PowerShell 中检查：

Get-FileHash -LiteralPath 'D:\Games\PvZ\PlantsVsZombies.exe' -Algorithm SHA256

尚未覆盖所有关卡和模式。冒险 1-5 支持戴夫对话、铲子教学及传送带坚果保龄球；其他特殊关卡仍需逐一验证。回放、金币编辑、全植物解锁和任意存档编辑也尚未实现。

快速开始

使用 EXE 安装器

1. 从 Releases 下载并运行 PvZ-MCP-版本号-Setup.exe。
2. 选择工具安装目录，默认 D:\Programs\PvZ-MCP。
3. 保持默认的“自动发现已打开的游戏”，无需选择游戏路径。需要 MCP 代为启动游戏时，可选填自己的 EXE 路径。
4. 点击“安装 / 更新”。安装器自带 Node.js、Python 和 MCP 依赖，无需另行下载。
5. 将安装目录生成的 mcp-config.json 合并到 AI 客户端的 MCP 配置中，重新连接服务。配置格式可能需要按客户端要求转换。
6. 自行打开受支持的原版游戏，让 AI 调用 pvz_status / pvz_list_games，再用 pvz_attach 连接。pvz_get_state 也会自动接入并暂停战斗。

没有运行游戏时，MCP 返回 NOT_RUNNING。可以自行启动游戏，或调用 pvz_launch_game(game_path="D:\Games\PvZ\PlantsVsZombies.exe")。成功连接后会记住启动路径，后续可省略。多个受支持游戏同时运行时，须从 pvz_list_games 返回值中选择 PID；不会静默选取其中一个。

安装器不会自动修改 AI 客户端配置，也不会启动或改写所选游戏。

从源码构建的 ZIP 离线包，解压后可使用 Install.cmd，或通过命令行安装：

.\Install.ps1 -InstallDir 'D:\Programs\PvZ-MCP' -NonInteractive

可选：记住游戏启动路径：

.\Install.ps1 -InstallDir 'D:\Programs\PvZ-MCP' -GamePath 'D:\Games\PvZ\PlantsVsZombies.exe' -NonInteractive

**源码仓库与安装包不同。**从源码运行和构建 EXE 请参阅开发说明。

启动方式

安装完成后，可点击「打开控制面板」，或双击安装目录的 PvZ-MCP-Control.exe。面板自动只读刷新状态与文字棋盘，不会暂停游戏或中断推进。植物使用彩色简称，支持同格多层植物；僵尸按原生横坐标显示，啃咬时变为红色。点击植物格子或僵尸可查看全名、坐标与血量。读取期间若游戏发生更新，会重试；无法取得一致数据时会标明仍是上次数据。面板与 AI 共享控制状态，手动操作会影响当前进程。关闭面板不会关闭游戏或 MCP。

面板可单独使用；让 AI 游玩仍需在 AI 客户端配置 MCP。更新或回退后，面板入口会读取当前启用版本。

棋盘页提供「运行」和「暂停」，游戏布局自动更新。同排僵尸使用稳定的纵向错位以便区分；点击可查看实际坐标。「运行」和定时推进会自动解除游戏失去焦点时的暂停，切回控制台后也能继续运行。手动打开的设置菜单仍会暂停游戏，需关闭后再继续。

可以先双击原版游戏，再启动或连接 MCP；无需退出游戏。默认识别 PlantsVsZombies.exe、popcapgame1.exe 和名称含“植物大战僵尸”的 EXE。自行改名的文件可通过 pvz_list_games(pid=...) / pvz_attach(pid=...) 指定，或选填启动路径。

工具在接入已有进程或启动新游戏时加载内存桥接，不改写游戏 EXE 或资源文件；关闭游戏后桥接自然消失。游戏仍会正常保存进度，管理员改档操作也会写入存档。

同一时间建议只运行一份游戏，并由一个客户端控制。AI 客户端需要具备本机 MCP 执行能力。

让 AI 开始游玩

连接成功后，可以向 AI 提出这样的要求：

通过 PvZ MCP 按当前存档进度开始冒险，不增加阳光。每轮暂停读取 JSON，自主决定种植和下一次等待时长，保持 1 倍速，并用简短观战说明解释操作。

典型流程：

发现并连接游戏 → 开始或继续关卡 → 读取暂停快照 → 判断并操作 → 推进一段时间 → 再次判断

默认每次推进 2 秒游戏时间，也可以由 AI 按局势选择更长的间隔。种植遵守阳光、冷却与地形规则。选关参数 level 只在明确指定关卡时使用；省略时按当前存档进度开始。

工具参数、身份校验、异步推进和领奖处理见调用说明。AI 也可直接调用 pvz_help；pvz_status 和 pvz_get_state 的 guidance 会说明当前可用操作和下一步。

MCP 工具列表

当前提供 26 个工具。具体操作受当前场景、模式和解锁状态限制。

| 工具 | 用途 | | --- | --- | | pvz_help | 无需启动游戏即可查询工具用法、参数约定和操作流程 | | pvz_continue_dialogue | 按句推进冒险 1-5 的戴夫对话 | | pvz_shovel | 通过原生铲子流程挖掉单层植物，支持 1-5 教学 | | pvz_status | 只读查询游戏进程、场景和控制状态 | | pvz_check_update | 查询本仓库新版本、安装器下载地址与 SHA-256 | | pvz_list_games | 发现正在运行的游戏，返回版本校验结果、PID 和会话标识 | | pvz_attach | 连接已打开的受支持原版，无需重启，保留当前棋盘 | | pvz_launch_game | 启动受支持的游戏并加载桥接，或复用已连接的进程 | | pvz_list_modes | 查询模式目录和支持信息 | | pvz_start_game | 开始冒险或指定模式，支持显式选关 | | pvz_return_to_menu | 返回主菜单，离开当前关卡 | | pvz_get_state | 暂停并读取一致的 JSON 游戏状态 | | pvz_observe | 不暂停地读取棋盘，验证读取前后未更新；失败可重试 | | pvz_pause | 暂停模拟，保留控制入口 | | pvz_advance | 推进指定时长或更新次数，然后再次暂停 | | pvz_resume | 持续运行，可指定倍速 | | pvz_select_seeds | 按实际解锁情况选择卡组并开始 | | pvz_can_place | 检查卡槽、费用、冷却和格子合法性 | | pvz_place_plant | 普通关卡扣阳光并触发冷却；传送带关卡消耗卡牌 | | pvz_collect | 拾取阳光、钱币、植物卡片、铲子、来信、奖励钱袋和钻石袋 | | pvz_read_letter | 返回当前来信的中文文字、摘要及转录来源，无需识图 | | pvz_set_presentation | 设置倍速、观战提示、说明保留时间和默认推进时长 | | pvz_set_commentary | 显示 AI 的简短打算和本次操作说明 | | pvz_get_save_info | 只读查询当前用户存档、进度和校验信息 | | pvz_admin_set_progress | 管理员功能：备份后持久修改冒险进度 | | pvz_admin_set_sun | 管理员功能：直接设置局内阳光 |

普通种植与选卡当前覆盖冒险和植物僵尸的相应原生规则，模仿者暂不支持。模式出现在目录中，不代表已解锁或已完成实机验证。

管理员接口会改变正常游戏状态，应按使用者明确要求调用。返回主菜单会离开当前关卡，未结算的局内进度可能丢失。

升级与回退

关闭游戏并断开 MCP，运行新版 EXE 安装器或 ZIP 离线包，选择原安装目录即可升级。用户配置和备份会保留，重新连接 MCP 后使用新版。

需要回退时，在安装目录运行：

.\Manage.ps1 -Action Rollback

回退只切换工具版本，不恢复游戏存档。

自动检查更新

连接 MCP 后，工具在后台从 本仓库 Releases 检查新版，默认每 24 小时一次。检查结果会加入 pvz_status 的 update 字段；发现新版时向客户端输出提示。客户端是否直接显示提示取决于其日志界面，AI 也可读取状态后告知你。

预览版默认同时检查正式版和预览版，正式版默认仅检查正式版。工具按版本号比较，忽略草稿和缺少 EXE 安装器的 Release。网络失败或 GitHub 限流会稍后重试，不阻塞 MCP 连接或游戏操作。

可以让 AI 调用 pvz_check_update 立即检查，也可在安装目录运行：

.\Manage.ps1 -Action CheckUpdate

检查更新只获取版本元数据，不会自动下载、安装或重启。升级时下载提示中的 EXE，再选择原安装目录。0.3.1-preview.1 及更早版本需要先手动升级一次，才具备此功能。

自动检查开关、更新频道和代理配置见调用说明。

开发与贡献

欢迎 fork 添加游戏版本适配、补充测试或扩展工具。源码结构、运行环境和测试方法见开发说明。

新增适配需要核实函数地址、调用方式和对象结构，并补上验证结果；请保留版本校验，更新兼容性表。请勿提交游戏文件、用户存档或运行日志。

许可

Copyright (c) 2026 ZhangAo1999。原项目：https://github.com/ZhangAo1999/pvz-mcp。

从 0.3.2-preview.1 起，项目工具代码使用 GNU GPL v3，仅第 3 版（GPL-3.0-only）。二次分发时需保留适用的作者版权和许可证声明，标明修改，并按 GPL 要求提供对应源码；私人修改自用无需公开。作者和来源信息见 NOTICE。

已发布的 0.3.1-preview.1 保留其 MIT 许可。第三方依赖遵循各自许可证，见第三方声明。

本项目与 EA / PopCap 无隶属或授权关系。使用工具仍需遵守适用的游戏许可协议及法律。

奖励与信件

pvz_collect 支持普通阳光、金币、最终种子包、铲子，以及僵尸来信（类型 15）、奖励钱袋（18）和钻石袋（20）。领取后使用 pvz_advance 播放原生过关动画。

pvz_read_letter 可以读取地上或奖励页当前信件的中文文字和摘要，无需模型识图。文字来自本版本游戏图片的人工转录，保留原文错别字；未确认的文字会明确标记。状态也会返回 rewards / award.letter。

新启动的游戏在 AI 暂停时保留菜单按钮交互，战斗、阳光生产及冷却继续冻结。更新前已经运行的旧桥接可继续读取状态及领取奖励；菜单修复在新版桥接加载后生效；升级前的旧桥接若缺少该功能，需要重启一次游戏，再通过 MCP 接入。