Joern MCP Server

Joern MCP 服务

一个简单的 Joern MCP 服务。

项目介绍

本项目是基于 Joern 的 MCP 服务，提供一系列功能，帮助开发者进行代码审查和安全分析。

环境要求

• Python >= 3.10（默认 3.12）和 uv
• Joern

安装步骤

1. 将项目克隆到本地：

   git clone https://github.com/sfncat/mcp-joern.git
   cd mcp-joern
   

2. 安装 Python 依赖：

   uv venv .venv
   source .venv/bin/activate
   uv sync
   

项目结构

├── server.py                       # MCP Server main program
├── test_mcp_client.py              # Test program for joern server and mcp tool
├── test_sc_tools.py                # Direct test program for sc tools
├── common_tools.py                 # Common utility functions
├── server_tools.py                 # Server utility functions
├── server_tools.sc                 # Scala implementation of server utility functions
├── server_tools_source.sc          # Scala implementation of server utility functions,use sourceCode to get the source code of method
├── requirements.txt                # Python dependency file
├── sample_cline_mcp_settings.json  # Sample cline mcp configuration file
└── env_example.txt                 # Environment variables example file

使用方法

1. 启动 Joern 服务：

   joern -J-Xmx40G -J-XX:CompressedClassSpaceSize=1g -J-XX:MaxMetaspaceSize=2g \
         --server --server-host 127.0.0.1 --server-port 16162 \
         --server-auth-username user --server-auth-password password --import server_tools.sc
   Or
   joern -J-Xmx40G -J-XX:CompressedClassSpaceSize=1g -J-XX:MaxMetaspaceSize=2g \
         --server --server-host 127.0.0.1 --server-port 16162 \
         --server-auth-username user --server-auth-password password --import server_tools_source.sc
   

   为什么需要额外的 JVM 标志。 两项默认值都太小，而且只有在长时间使用后才会出现问题，因此故障看起来像是服务已停止，而不是 JVM 配置问题：

   • -XX:CompressedClassSpaceSize=1g — Joern REPL 每个查询都会编译一个类 （rs$line$N）。默认类空间（128m）在几千次查询后就会耗尽，之后每个查询都会失败，并出现 NoClassDefFoundError: Could not initialize class rs$line$NNNN。
   • -XX:MaxMetaspaceSize=2g — 为元空间预留充足空间，使其与类空间相匹配。
   • -J-Xmx… — 根据 CPG 大小设置堆大小。堆太小时，查询会超时（而不是发生 OOM）。我们为约 400 MB 的 CPG 使用 -Xmx60G。 如果在 Windows 下使用，可能需要通过命令行或系统环境变量设置 JVM 系统变量。

   set _JAVA_OPTIONS=-Dfile.encoding=UTF-8
   

   将 joern 日志级别设为 ERROR

   set SL_LOGGING_LEVEL=ERROR //windows
   export SL_LOGGING_LEVEL=ERROR //linux
   

   如果出现以下警告

   Unable to create a system terminal, creating a dumb terminal (enable debug logging for more information)
   

   可以通过设置环境变量来禁用

   set TERM=dumb
   export TERM=dumb
   

   恢复默认行为

   set TERM=xterm-256color
   export TERM=xterm-256color
   

2. 将 env_example.txt 复制为 .env 修改配置信息，使其与 joern 服务的启动配置相匹配

3. 运行连接测试： 修改 test_mcp_client.py 中的信息，以确认 joern 服务正常运行

   uv run test_mcp_client.py
   Starting MCP server test...
   ==================================================
   Testing server connection...
   [04/16/25 20:38:54] INFO     Processing request of type CallToolRequest                                                                                                                     server.py:534
   Connection test result: Successfully connected to Joern MCP, joern server version is XXX
   

4. 配置 MCP 服务 在 cline 中配置 MCP 服务，参见 sample_cline_mcp_settings.json。

5. 使用 MCP 服务 向大模型提问，参见 prompts_en.md

开发说明

• .env 文件用于存储环境变量
• .gitignore 文件定义 Git 版本控制中要忽略的文件
• pyproject.toml 定义项目的 Python 配置
• MCP 工具开发
  • 在 server_tools.sc 中实现，在 server_tools.py 中添加定义，并在 test_mcp_client.py 中添加测试

贡献指南

欢迎提交 Issues 和 Pull Requests，帮助改进项目。

欢迎添加更多工具。

参考资料

https://github.com/flankerhqd/jebmcp

https://docs.joern.io/server/

https://docs.joern.io/interpreter/

更新日志

v1.2.0（2026-09-10）

服务端调用图工具（性能）

• 在 server_tools.sc 中新增 Scala 辅助函数：get_methods_by_name（通过索引进行 nameExact 查找，取代对整个 CPG 执行 .filter(_.fullName.contains(...)) 扫描；大型 CPG 上此类扫描会超时）、get_callee_chain（服务端 BFS，一次 HTTP 往返即可返回完整调用链——方法全名及代码，跳过 JDK／框架被调用者）和 get_callee_chain_names（仅返回名称，不含代码）。
• 新增 MCP 工具以公开这些功能：get_callee_chain_server、get_methods_by_name。
• 效果：解析一条调用链的 HTTP 往返次数从约 30 次降至 1 次。

HTTP 客户端加固（server.py）

• joern_remote 现在使用保持连接的 requests.Session，并启用连接池。
• 对瞬时故障重试 3 次，但遇到 401／403 时快速失败（认证错误不属于瞬时故障）。
• 失败时返回明确的 ERROR: ... 字符串，而非 None，以便调用方区分失败和合法的空结果。

修复

• 凭据键兼容性：随附的 .env 使用 USER_NAME／PASSWORD，而主机配置注入的是 JOERN_AUTH_USERNAME／JOERN_AUTH_PASSWORD。之前只读取后者，因此未通过主机注入环境变量启动时（包括随附的 test_mcp_client.py）都会以静默的 401 错误失败。现在两种名称均可使用。
• FastMCP 兼容性：fastmcp 2.x 已移除构造函数参数 log_level；现在会在 try/except 中传入该参数，并使用 FASTMCP_LOG_LEVEL 作为回退值。

文档与维护

• 启动命令现在包含 -XX:CompressedClassSpaceSize=1g -XX:MaxMetaspaceSize=2g（默认值为何只会在长时间使用后导致失败，请参阅“启动 Joern 服务”下的说明）。
• 代码注释仅使用英文；中文内容仅放在 README_cn.md 和 prompts_cn.md 中。
• .gitignore：忽略本地 CPG 文件（*.cpg）、备份文件（*.bak-*）以及用于注入本地凭据的 run_verify.sh 包装脚本。
• 版本升级至 1.2.0。

v1.3.0（2026-09-10）

• tests/fixture/：自包含的 Android 测试样例（自制源码 + build_fixture.sh），可构建一个约 12 KB、针对 API 36／SDK 扩展级别 17 的 APK 及其匹配的 CPG。此前曾导致工具出错的所有结构均各出现一次：业务入口为 handleBroadCastReceive()（而非 onReceive）的自定义基接收器、跨类和接口的 4 跳委派链、重名的简单方法名、匿名内部类、位于调用链末端的 SharedPreferences 写入（hd_member）、调用链工具必须跳过的框架调用，以及受权限限制的接收器。
• test_mcp_client.py 现在是基于断言的回归门禁，针对该测试样例检查调用链／查找工具、旧版查询和错误路径，并在失败时以非零状态退出。临时的 verify_mcp.py 已合并到其中。
• 测试样例 APK 的版本与此软件包（pyproject.toml）一致，因此 tests/fixture/fixture.apk 和 fixture.cpg 会与服务端一同进行版本管理。
• 文档和工具帮助不再使用旧的 NFC 示例，改用该测试样例。
• 版本从 1.2.0 升级至 1.3.0。

测试

cd tests/fixture && ./build_fixture.sh --cpg   # fixture.apk + fixture.cpg
cd ../.. && uv run test_mcp_client.py          # protocol-level regression gate