Nullprint

nullprint-mcp

面向 Nullprint（多配置文件浏览器）的 MCP 服务。它允许任何支持 MCP 的 AI Agent（Claude Code、Claude Desktop、OpenAI Codex、Kimi 等）创建浏览器配置文件、启动配置文件、运行一致性检查，并操作运行中的配置文件内的页面。

该服务是本地 Nullprint 守护进程 HTTP API 的轻量封装：每个工具都对应一个守护进程端点。守护进程、浏览器内核和指纹引擎随 Nullprint 桌面应用一起提供，不属于此软件包。

要求

• 已安装并运行 Nullprint 桌面应用（Windows 或 macOS），且已登录。下载地址：https://nullprint.ai
• 同一台机器上安装了 Python 3.11+。运行此服务最简单的方式是使用 uv，它会在首次使用时安装软件包。

安装

# Claude Code
claude mcp add nullprint -- uvx nullprint-mcp

# OpenAI Codex
codex mcp add nullprint -- uvx nullprint-mcp

Claude Desktop、Kimi 及其他使用 mcpServers 配置文件的客户端：

{
  "mcpServers": {
    "nullprint": {
      "command": "uvx",
      "args": ["nullprint-mcp"]
    }
  }
}

不使用 uv：运行 pip install nullprint-mcp，然后将 nullprint-mcp 用作命令（不带参数）。

无需配置端口或密钥：服务会从 ~/.nullprint/daemon.json 读取运行中守护进程的端口和 API 密钥，该文件由桌面应用在启动时写入。如需连接其他位置的守护进程，请传入 --daemon-url http://host:port（或为 localhost 传入 --port 7801），并设置 NULLPRINT_API_KEY。解析顺序如下，优先级从高到低：

1. --daemon-url / --port
2. NULLPRINT_DAEMON_URL
3. NULLPRINT_PORT
4. ~/.nullprint/daemon.json（NULLPRINT_HOME 可更改目录）

如果守护进程未运行，工具会明确提示，而不会抛出连接跟踪信息。

工具

工具	功能	守护进程端点
profiles_list	列出所有配置文件及其状态（运行中 / 空闲）、出口和账本元数据	GET /profiles
profile_start	为配置文件打开浏览器会话；返回操作端点	POST /sessions/{name}
profile_stop	停止该配置文件的浏览器（会话或由应用启动的窗口）	DELETE /sessions/{name} → 回退到 POST /profiles/{name}/stop
profile_create	创建配置文件（生成并冻结指纹），可选设置代理、账本和启动页面	POST /profiles
profile_settings	更改现有配置文件的显示设置——目前为 force_dark（强制网页使用深色模式，默认关闭；合并到其启动设置中）	GET + PATCH /profiles/{name}
profile_checkup	一致性检查，返回 {summary, checks}	GET /profiles/{name}/checkup?live=
proxy_check	无状态代理测试：出口 IP、国家/地区、延迟	POST /proxy-check
profile_delete	软删除至回收站（可恢复）；运行中时拒绝删除	DELETE /profiles/{name}
trash_list	只读列出回收站中可恢复的配置文件	GET /trash
profile_restore	从回收站恢复，并保留指纹、代理和登录信息	POST /trash/{name}/restore
session_goto	导航至会话的当前页面	POST /sessions/{name}/goto
session_snapshot	获取当前页面的无障碍树（查找选择器、读取状态）	GET /sessions/{name}/snapshot
session_click_selector	通过 CSS 选择器点击元素	POST /sessions/{name}/click_selector
session_fill_selector	通过 CSS 选择器填充输入框	POST /sessions/{name}/fill_selector
session_press	发送按键（例如 Enter）	POST /sessions/{name}/press
session_eval	在页面上运行 JavaScript，返回 {ok, result}	POST /sessions/{name}/eval
session_tabs	列出会话的标签页及当前活动标签页	GET /sessions/{name}/tabs
session_switch_tab	将某个标签页置于前台	POST /sessions/{name}/switch_tab
session_dialog	响应页面上打开的 JavaScript 对话框（alert / confirm / prompt / beforeunload）：accept 或 dismiss	POST /sessions/{name}/dialog

编写提示词时需要注意的事项：

• session_* 工具需要已打开的会话。 它们操作由 profile_start 打开的常驻会话；在没有会话的身份上调用会返回 409。选择器使用 CSS，而非 XPath 或角色/名称；如果不知道选择器，请先调用 session_snapshot。
• 对话框会像在普通浏览器中一样保持打开。 当警告框 / 确认框 / 提示框打开时，页面会被阻塞，session_* 工具会失败并返回 409，同时指出对话框；使用 session_dialog 回应后再重试。由你自己的 session_goto 或点击触发的 beforeunload 会自动接受。
• session_eval 会返回一个封装对象。 页面端 JavaScript 错误会作为数据返回（{ok: false, error, error_type}），而非工具调用失败；result 的类型与表达式的类型一致。
• profile_stop 分两个层级。 身份可以作为常驻会话运行，也可以作为从应用启动的窗口运行。该工具会先尝试停止会话，失败时再回退到应用级停止；对空闲身份而言，此操作是幂等的。它会返回 {name, stopped, closed}。
• profile_create 不会硬编码内核。 将 engine 留空即可使用应用默认值；未知值会返回 422，并列出可选项。
• proxy_check 的失败会作为数据返回。 无法访问代理时会返回 {ok: false, error}；只有无法访问守护进程时才会抛出异常。
• profile_start 会返回 cdp_endpoint（一个 ws:// DevTools 地址），适用于在应用中开启了外部调试功能的 Chrome 内核（默认关闭；依次选择 Edit → Advanced → External debugging，完成二次验证后重新打开身份），以便外部工具连接。否则该值为 null，并附有说明原因的 cdp_unavailable（原因代码）和 cdp_note。从外部驱动的会话会绕过 Nullprint 的一致性保护：外部工具可以设置与身份冻结的指纹相矛盾的视口、语言或时区，从而导致身份被检测出来。请优先使用 session_* 工具；如果必须连接，请勿更改身份未声明的任何设置。

刻意不提供的功能

永久删除身份（DELETE /trash/{name}）会销毁其登录信息，且无法撤销。我们有意不将其设为工具：清空回收站必须由用户在桌面应用中操作。profile_delete 的描述会指示 Agent 说明这一点，而不是尝试绕过限制；测试也会扫描每个工具的源代码，确保清除端点未被纳入。

开发

pip install -e ".[dev]"
pytest tests
nullprint-mcp --help

工具位于 nullprint_mcp/tools.py（TOOLS 元组）中；添加工具时无需更改 server.py 和 __main__.py。不得向 stdout 打印任何内容：stdout 是 MCP 通道。

许可证

MIT。版权所有 (c) 2026 HENGCHENG LLC。

---

中文说明

这是 Nullprint（多身份指纹浏览器）的 MCP 服务：Claude Code、Claude Desktop、OpenAI Codex、Kimi 等任何支持 MCP 的 AI 都可以用它创建身份、启动浏览器、执行一致性检查，并驱动身份中的网页。它只是本地 daemon HTTP 接口上的一层薄封装，每个工具都对应 daemon 的一个端点；daemon、浏览器内核和指纹引擎随 Nullprint 桌面应用发布，不包含在本软件包中。

前提：本机已安装并登录 Nullprint 桌面应用；本机已安装 Python 3.11+，推荐使用 uv（首次运行时会自动安装软件包）。

接入：

claude mcp add nullprint -- uvx nullprint-mcp      # Claude Code
codex mcp add nullprint -- uvx nullprint-mcp       # OpenAI Codex

Claude Desktop、Kimi 等使用配置文件的客户端，可在 mcpServers 中添加 {"command": "uvx", "args": ["nullprint-mcp"]}。如果没有 uv，请运行 pip install nullprint-mcp，并将命令改为 nullprint-mcp。

无需配置端口和密钥：服务会自动读取桌面应用写入 ~/.nullprint/daemon.json 的端口和 API Key。若要连接其他机器上的 daemon，请传入 --daemon-url 并设置 NULLPRINT_API_KEY。

18 个工具：profiles_list、profile_start、profile_stop、profile_create、profile_settings、profile_checkup、proxy_check、profile_delete、trash_list、profile_restore，以及 8 个会话工具 session_goto / snapshot / click_selector / fill_selector / press / eval / tabs / switch_tab（使用前先调用 profile_start）。永久删除身份故意不设为工具：清空回收站只能由用户在桌面应用中操作。