完整的 Model Context Protocol (MCP) Java 调试服务器使用说明
Java Debug MCP Server 是一个基于 Model Context Protocol 的调试服务器,允许 Claude(或其他支持 MCP 的 LLM)直接调试 Java 程序。
- 🔌 附加到运行中的 JVM 进行调试
- 🚀 启动新的 Java 进程并调试
- 📍 设置和管理断点(支持智能短类名后缀匹配及消歧报错)
⚠️ 异常断点拦截(可在任意指定的 Java 异常抛出位置自动暂停)- 📢 控制台输出实时转发(将调试目标的 stdout/stderr 实时流式推送至客户端)
- 👀 查看局部变量和对象字段(支持防止循环引用的深度递归展示)
- 📊 查看线程和堆栈信息
- ⏮️ 单步执行(Step Over/Into/Out)
- 🔄 继续执行控制
| 软件 | 最低版本 | 推荐版本 |
|---|---|---|
| Java | 17 | 17+ |
| Maven | 3.6+ | 3.9+ |
| Claude Desktop | 最新版 | 最新版 |
- Windows 10/11
- macOS 11+
- Linux (主流发行版)
# 克隆或下载项目到本地
cd /path/to/workspace
# 项目位于: E:/java_workspace/debug_mcpcd E:/java_workspace/debug_mcp
mvn clean package编译成功后会生成 JAR 文件:
target/debug-mcp-1.0.0.jar (约 2.3 MB)
java -jar target/debug-mcp-1.0.0.jar应该看到启动信息:
========================================
Java Debug MCP Server v1.0.0
========================================
...
编辑配置文件: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"java-debugger": {
"command": "java",
"args": [
"-jar",
"E:\\java_workspace\\debug_mcp\\target\\debug-mcp-1.0.0.jar"
],
"env": {}
}
}
}编辑配置文件: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"java-debugger": {
"command": "java",
"args": [
"-jar",
"/path/to/debug_mcp/target/debug-mcp-1.0.0.jar"
],
"env": {}
}
}
}配置完成后,必须完全重启 Claude Desktop:
- 完全退出 Claude Desktop
- 重新启动应用程序
- 检查 MCP 连接状态
java -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y \
-cp /path/to/classes com.example.YourMainClass在 Claude 对话中使用工具启动。
配置完成后,在 Claude Desktop 对话中直接使用调试功能:
用户: 请帮我调试这个 Java 程序
Claude: 我来连接到你的 Java 程序并设置断点...
| 工具名称 | 功能 | 参数 |
|---|---|---|
connect_attach |
附加到运行中的 JVM | host (默认: localhost), port |
connect_launch |
启动并调试新进程 | mainClass, classpath, vmArgs, programArgs |
disconnect |
断开连接 | - |
get_status |
获取调试器状态 | - |
| 工具名称 | 功能 | 参数 |
|---|---|---|
set_breakpoint |
设置断点 | className (类名,支持短类名后缀匹配), lineNumber (行号) |
clear_breakpoint |
清除断点 | breakpointId (断点 ID) |
list_breakpoints |
列出所有断点 | - |
set_exception_breakpoint |
设置异常断点 | exceptionClassName (异常类全名或短类名), caught (是否捕获时触发,可选,默认 true), uncaught (是否未捕获时触发,可选,默认 true) |
clear_exception_breakpoint |
清除异常断点 | breakpointId (异常断点 ID) |
| 工具名称 | 功能 | 参数 |
|---|---|---|
continue_execution |
继续执行 | threadId (可选) |
step_over |
单步跳过 | threadId (可选) |
step_into |
单步进入 | threadId (可选) |
step_out |
单步跳出 | threadId (可选) |
| 工具名称 | 功能 | 参数 |
|---|---|---|
get_local_variables |
获取局部变量 | threadId (可选), frameIndex (默认: 0) |
get_fields |
获取对象字段 | objectId (对象 ID) |
list_threads |
列出所有线程 | - |
list_classes |
列出已加载的类 | pattern (可选过滤) |
list_stacktrace |
获取线程堆栈 | threadId (可选) |
// com/example/App.java
package com.example;
public class App {
public static void main(String[] args) {
int sum = 0;
for (int i = 1; i <= 10; i++) {
sum += i;
}
System.out.println("Sum: " + sum);
}
}# 编译 (带调试信息)
javac -g -d bin src/com/example/App.java
# 启动 (可调试模式)
java -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y \
-cp bin com.example.App用户: 请帮我调试 com.example.App,我想看看 sum 变量的变化
Claude: 好的,我来连接到你的程序...
[连接到 localhost:8000]
[设置断点在 App.java:6]
[继续执行]
[断点命中]
[当前局部变量:
int sum = 0
int i = 1]
变量 i 当前是 1,sum 是 0。继续单步执行吗?
# 启动 Spring Boot 应用 (可调试模式)
java -agentlib:jdwp=transport=dt_socket,server=y,address=5005,suspend=y \
-jar target/myapp-1.0.0.jar然后在 Claude 中:
用户: 连接到 localhost:5005 的 Spring Boot 应用,在
com.example.controller.UserController 的 getUser 方法设置断点
用户: 请帮我启动并调试 com.example.Calculator 类
Claude: 好的,我来启动这个程序...
[调用 connect_launch:
mainClass: "com.example.Calculator"
classpath: "target/classes"]
程序已启动,正在调试...
A: 检查以下事项:
- JAR 文件路径是否正确(使用绝对路径)
- 路径中的反斜杠需要转义为双反斜杠 (Windows) 或使用正斜杠
- 确认 Claude Desktop 已完全重启
- 查看 Claude Desktop 日志文件
A: 确保:
- 目标程序正在运行并显示 "Listening for transport dt_socket..."
- JDWP 端口号正确(默认 8000)
- 没有防火墙阻止连接
suspend=y表示程序会等待调试器连接
A: 检查:
- 编译时使用
-g参数包含调试信息 - 行号是否正确
- 类名是否完全匹配(包括包名)
- 类是否已被加载
A: 确保:
- 使用完整的类名(包括包名)
- 类在 classpath 中
- 类已被 JVM 加载
A: 可能原因:
- 变量被编译器优化掉
- 确保使用
-g编译包含所有调试信息javac -g:lines,vars,source ...
# 方式 1: 使用 mvnDebug
mvnDebug test
# 然后连接到 localhost:8000
# 方式 2: 使用 Maven 插件
mvn exec:exec -Dexec.executable="java" \
-Dexec.args="-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y -cp %classpath com.example.Main"# 添加到 build.gradle
application {
applicationDefaultJvmArgs = ['-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y']
}
# 然后运行
gradle runjava -agentlib:jdwp=transport=dt_socket,server=y,address=*,suspend=y \
-jar myapp.jar在 Claude 中指定远程服务器地址:
用户: 连接到 192.168.1.100:8000 进行调试
# Dockerfile
FROM openjdk:17
EXPOSE 8000
ENTRYPOINT ["java", "-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y", "-jar", "app.jar"]# 运行容器
docker run -p 8000:8000 myapp
# 在 Claude 中连接到 localhost:8000-agentlib:jdwp=<name1>=<value1>,<name2>=<value2>...
| 参数 | 值 | 说明 |
|---|---|---|
transport |
dt_socket |
使用 socket 传输 |
server |
y/n |
JVM 是否作为服务器 |
address |
8000 或 *:8000 |
监听地址和端口 |
suspend |
y/n |
启动时是否暂停 |
allow |
* |
允许所有主机连接 |
# 等待调试器连接
-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y
# 启动后不等待
-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=n
# 允许远程连接
-agentlib:jdwp=transport=dt_socket,server=y,address=*:8000,suspend=y# 启动程序
java -agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=y -cp bin com.example.Main
# 在 Claude 中
"连接到 localhost:8000""在 com.example.Main 的第 15 行设置断点"
"显示当前的局部变量"
"查看 objectId 为 123abc 的对象的字段"
"单步执行"
"单步进入"
"单步跳出"
"继续执行"
E:/java_workspace/debug_mcp/
├── pom.xml # Maven 配置
├── README.md # 项目说明
├── USER_GUIDE.md # 本文档
├── TEST.md # 测试指南
├── target/
│ ├── debug-mcp-1.0.0.jar # 可执行 JAR
│ └── test-classes/ # 测试类
├── src/
│ ├── main/java/com/debugger/mcp/
│ │ ├── Main.java # 入口
│ │ ├── McpServer.java # MCP 服务器
│ │ ├── handler/ToolHandler.java # 工具处理器
│ │ ├── debugger/ # 调试器实现
│ │ └── model/ # 消息模型
│ └── test/java/
│ └── com/example/ # 测试程序
- 查看 README.md 了解项目概述
- 查看 TEST.md 了解测试方法
- 查看源代码中的注释了解实现细节
- v1.1.0 - 进阶功能版本 (当前最新)
- 控制台输出转发:不再丢弃被调进程的标准输出和错误流,通过 MCP 协议通道(
STDOUT/STDERR事件类型)实时推送到客户端。 - 异常断点支持:新增设置/清除异常断点工具,安全读取底层私有
detailMessage规避死锁,能够在捕获或未捕获异常抛出时自动挂起。 - 容错类名解析:设置行断点支持输入短类名(如
Calculator而非完整的com.example.Calculator),后缀模糊匹配;如匹配到多项则自动报错列出候选供消歧。
- 控制台输出转发:不再丢弃被调进程的标准输出和错误流,通过 MCP 协议通道(
- v1.0.0 - 初始版本
- 支持附加到运行中的 JVM
- 支持启动新进程调试
- 断点管理
- 变量查看
- 单步执行
- 线程和堆栈信息查询