Swing MCP

swing-mcp

让 AI 助手操作 Java 桌面应用——Swing 和 JavaFX——截取界面快照、点击、输入、填写表单、读取表格和树形视图、操作菜单和对话框。灵感来自 chrome-devtools-mcp，但目标是正在运行的 Java UI，而不是 HTML 页面。

一组工具即可操作任一工具包，也可同时操作混合使用两者的应用——你无需告诉它自己使用的是哪一种。

大量商业软件都是 Java 桌面软件——内部工具、ERP 客户端、销售点系统、实验室和物流系统——没有 API，也没有 Web UI，使用 Swing 编写，如今也越来越多地使用 JavaFX。Swing MCP 为这些软件开启一扇安全且经授权的窗口，通往 AI 时代：Claude 等助手可以查看界面并进行操作，而无需更改应用本身。

快速开始（Claude Desktop）

1. 确保 PATH 中有 JDK 21+。
2. 从最新版本下载 swing-mcp.mcpb。
3. 打开该文件——Claude Desktop 会将其作为扩展安装。
4. 让 Claude 对你的应用执行 launch_app（或通过 PID 对正在运行的应用执行 attach_to_app），然后即可开始操作。

使用其他 MCP 客户端？每个客户端都有一份指南和一段一分钟视频——Claude Code、VS Code + Copilot、Cursor、Devin Desktop（Windsurf）、IntelliJ IDEA、Codex CLI、Gemini CLI：docs/installation.md · 视频。想看完整版本？3 分钟安装与首次使用视频。使用 JavaFX 应用？观看实时操作演示（96 秒，展示来自真实 MCP 日志的每次工具调用）。

需要将它连接到你自己的应用——或者为企业运行的其他软件提供 MCP 连接器？CrossTech 可以为你构建：crosstech.solutions/swing-mcp。

模块

• swing-mcp-server — Spring Boot MCP 服务（stdio 传输），提供自动化工具。
• swing-mcp-agent — 加载到目标 JVM 中的 Java Agent（启动时通过 -javaagent 加载，或按 PID 动态加载）。运行仅限 localhost 的 JSON 行协议套接字服务端。包含每种受支持工具包各自的 UiToolkit 实现，并将每条命令路由到相应实现；参见 docs/adr/0001-multi-toolkit-agent.md。
• swing-mcp-common — 共享命令、DTO 类型和 UiToolkit 接口。
• swing-mcp-demo — 用于集成测试的 Swing 演示应用。
• swing-mcp-demo-fx — 用于集成测试的 JavaFX 演示应用（既通过工具包操作，也通过 stdio 上的真实服务操作）。

工作原理

MCP client (stdio) ──▶ swing-mcp-server ──localhost socket──▶ swing-mcp-agent (inside target JVM) ──▶ Swing EDT
                                                                                         └──▶ JavaFX Application Thread

1. MCP 客户端调用 launch_app（启动一个预加载了 Agent 的 JVM）或 attach_to_app（通过 PID 将 Agent 加载到正在运行的 JVM 中）。
2. Agent 在 swing.mcp.agent-port-min..max 范围内绑定一个仅限环回接口的端口，并通过响应文件将端口报告回来。
3. take_snapshot、click 和 fill 等工具会以 JSON 行命令的形式转发，并在所属工具包的 UI 线程上执行——Swing 的事件分派线程或 JavaFX 的 JavaFX 应用程序线程。
4. 组件 UID 会加上分配它们的工具包前缀（Swing 使用 comp-，JavaFX 使用 fx-），这样混合应用中的组件就不会混淆。
5. 每个工具都带有 MCP 注释（title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint），因此遵循这些注释的客户端可以直接放行 12 个只读工具，并在运行 stop_app、close_window 和 evaluate_java 前发出提示。

请参阅 docs/tools 中的完整工具文档（按类别划分的页面），或参阅 docs/tool-reference.md 中的单页快速参考。

Skills

skills 目录包含 Agent 技能（SKILL.md 文件），用于指导 AI 编码 Agent 如何高效使用 Swing MCP，包括核心工作流、UI 测试模式和故障排查。

构建

需要 JDK 21+ 和 Maven。

mvn verify

在无头环境中会跳过 GUI 集成测试；CI 会在 xvfb 下运行这些测试。JavaFX 集成测试会通过 failsafe 在 verify 阶段运行，因此单独运行 mvn test 不会执行这些测试。

运行

构建所有内容（或解压发布的 swing-mcp.mcpb——两个 JAR 位于其 server/ 文件夹中），然后向 MCP 客户端注册该服务（各客户端的说明请参阅 docs/installation.md，涵盖 Claude Desktop、Claude Code、VS Code、Cursor、Devin Desktop、IntelliJ IDEA、Codex CLI 和 Gemini CLI）：

{
  "mcpServers": {
    "swing": {
      "command": "java",
      "args": ["-jar", "/path/to/swing-mcp-server.jar"],
      "env": {
        "SWING_MCP_AGENT_JAR": "/path/to/swing-mcp-agent.jar"
      }
    }
  }
}

试着通过演示应用使用它：

1. 使用 java -jar swing-mcp-demo/target/swing-mcp-demo-1.3.0.jar 执行 launch_app （或使用 JavaFX 演示应用：swing-mcp-demo-fx/target/swing-mcp-demo-fx-1.3.0.jar）
2. 执行 take_snapshot 以发现组件 UID
3. 使用 click、fill、select_option 等工具进行交互

MCP Registry

此服务以 io.github.crosstech-solutions-bv/swing-mcp 的名称发布到 MCP Registry，并作为 MCPB 捆绑包附在 GitHub releases 中分发。发布流程请参阅 docs/registry-publishing.md。

安全说明

• Agent 仅监听环回接口。
• evaluate_java（在目标 JVM 中执行任意代码）默认处于禁用状态；可通过 swing.mcp.evaluate.enabled=true 启用。

完整的安全模型以及漏洞报告方式请参阅 SECURITY.md。

贡献

欢迎贡献——PR 工作流请参阅 CONTRIBUTING.md。发布历史记录在 CHANGELOG.md 中。

关于

Swing MCP 由 CrossTech 开发并维护。CrossTech 是一家 AI 优先的软件工作室。我们构建 MCP 连接器，将企业现有的软件——Web、云端和传统桌面软件——接入 AI 助手：crosstech.solutions/mcp。

许可证

MIT