接入 Claude Desktop

把 AgileMedic 注册成 Claude Desktop 的 MCP Server 后,你就能在对话里让 Claude 直接读你这台电脑的系统状态并帮你诊断。本页介绍两种接入方式:一键接入(推荐)和手动配置。

先读概览

如果你还不清楚"反向 MCP"是什么、AI 接入后能做什么、consent 授权如何保护你,请先看 反向 MCP Server 概览。

前置

• Windows 10/11 x64,已安装 AgileMedic。
• 已安装 Claude Desktop。
• 知道 sidecar agilemedic-mcp.exe 的绝对路径(与主程序 agile-medic.exe 在同一目录)。

写进配置的是 sidecar,不是主程序

Claude Desktop 要 spawn 的命令是 agilemedic-mcp.exe(独立 sidecar),不是 agile-medic.exe --mcp-stdio。一键接入会自动填对;手动配置时请注意别填成 GUI 主程序。

方式一:一键接入(推荐)

1. 打开 AgileMedic,进入 MCP Server 面板。
2. 找到 Claude Desktop 卡片。
3. 点该行的 一键接入 按钮。

AgileMedic 会自动:

• 定位 Claude Desktop 配置文件 %APPDATA%\Claude\claude_desktop_config.json(不存在则新建)。
• 把 agilemedic entry 的 command 指向当前 agilemedic-mcp.exe 的绝对路径。
• 写入前生成 .bak 备份,保留你已有的其他 MCP server 和配置。

接入后该行状态会变为 已接入。面板对每个目标做三态检测:

状态	含义
未接入	配置里没有 AgileMedic entry
已接入	entry 存在且指向当前 sidecar,正常可用
需重新接入	entry 存在但指向旧路径/别的 exe(如换了安装位置)→ 点"重新接入"修复
配置文件异常	配置文件 JSON 解析失败 → 需手动修正该文件

链路自检

面板顶部端点状态卡有自检按钮:它会真的 spawn 一次 sidecar 跑 initialize + tools/list 握手,回报协议版本、工具数、往返耗时。比"只看配置写没写"更可靠 —— 如果 exe 被杀软拦了或路径失效,自检能真实发现。

接入完成后,完全退出 Claude Desktop(见下方验证步骤),重新打开即可。

方式二:手动配置

1. 找到 Claude Desktop 配置文件

平台	路径
Windows	%APPDATA%\Claude\claude_desktop_config.json

文件不存在就新建。

2. 加入 AgileMedic MCP Server

把下面这段合并进配置文件(把路径换成你机器上 agilemedic-mcp.exe 的真实绝对路径):

{
  "mcpServers": {
    "agilemedic": {
      "command": "C:\\Program Files\\AgileMedic\\agilemedic-mcp.exe",
      "args": []
    }
  }
}

便携版/自定义安装目录示例:

{
  "mcpServers": {
    "agilemedic": {
      "command": "D:\\Tools\\AgileMedic\\agilemedic-mcp.exe",
      "args": []
    }
  }
}

JSON 转义

Windows 路径里的反斜杠 \ 在 JSON 中必须双写为 \\,否则 Claude Desktop 会启动失败。也可以改用正斜杠 /(C:/Program Files/AgileMedic/agilemedic-mcp.exe),同样有效。

sidecar 不需要额外参数

agilemedic-mcp.exe 启动后直接进入 stdio JSON-RPC 主循环,不需要任何命令行参数,所以 args 是空数组。(主程序 agile-medic.exe --mcp-stdio 那套旧写法仅为向后兼容保留,新接入一律用 sidecar。)

3. 重启 Claude Desktop

完全退出(托盘右键 → Quit,不是关窗口)→ 重新打开。

4. 验证

• 在对话框工具栏应能看到 MCP 工具入口 → 展开后有 agilemedic 的一组工具(21 个)。
• 试一句:"帮我看看我电脑现在的 CPU 和内存占用" → Claude 应自动调用 get_system_metrics。
• 再试:"列一下占内存最多的几个进程" → Claude 应调用 list_processes。

如果 Claude 尝试执行写操作(如结束进程),AgileMedic GUI 会弹窗请求你授权 —— 这一步需要主程序 agile-medic.exe 处于运行状态。

让写操作可用:保持 GUI 运行

只读工具即使 GUI 没开也能用(sidecar 自包含直接读系统)。但写操作(kill_process / clean_junk / stop_service 等)执行前要通过命名管道连 GUI 弹窗授权:

• GUI 正在运行 → 弹出 consent 对话框,你点"允许"才执行。
• GUI 没运行 → 授权失败,写操作不执行(返回错误)。这是 fail-safe 设计,不是 bug。

所以想让 AI 帮你动手清理/结束进程时,请先打开 AgileMedic 主程序。

故障排查

问题	原因 / 解决
工具列表里没有 agilemedic	1) 配置 JSON 语法错误 → 用 jsonlint.com 校验;2) command 路径不对 → 用绝对路径、反斜杠双写;3) Claude 没完全退出 → 托盘右键 Quit 后重开
报 "spawn failed" / 找不到程序	agilemedic-mcp.exe 路径写错或文件不存在 → 到安装目录确认文件名与路径
面板显示"需重新接入"	换了安装目录/升级后旧 entry 指向失效路径 → 点"重新接入"即可
面板显示"配置文件异常"	claude_desktop_config.json 本身 JSON 坏了 → 手动修正或从 .bak 恢复
只读工具能用,写操作总失败	AgileMedic 主程序(GUI)没开 → 写操作需要它弹窗授权,先启动主程序
授权弹窗一直不出现	主程序被关了,或命名管道 agilemedic-consent-v1 被占用 → 重启主程序
HKLM 启动项 / 服务操作失败	这类操作需要管理员权限 → 以管理员身份运行 AgileMedic 主程序

下一步

• 接入 Cursor —— Cursor / Cline 等编辑器
• 工具参考 —— 每个工具的完整参数与返回
• 反向 MCP Server 概览 —— consent 机制与安全说明