Nullprint README

nullprint-mcp

An MCP server for Nullprint, the multi-profile browser. It lets any MCP-capable AI agent (Claude Code, Claude Desktop, OpenAI Codex, Kimi, …) create browser profiles, launch them, run consistency check-ups and drive the pages inside a running profile.

The server is a thin layer over the local Nullprint daemon's HTTP API: every tool maps to one daemon endpoint. The daemon, the browser kernels and the fingerprint engine ship with the Nullprint desktop app and are not part of this package.

Requirements

Nullprint desktop app installed and running (Windows or macOS), signed in. Download: https://nullprint.ai
Python 3.11+ on the same machine. The easiest way to run the server is uv, which installs the package on first use.

Install

bash

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

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

Claude Desktop, Kimi and other clients that use an mcpServers config file:

config.json

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

Without uv: pip install nullprint-mcp, then use nullprint-mcp as the command (no args).

No port or key to configure: the server reads the running daemon's port and API key from ~/.nullprint/daemon.json, which the desktop app writes on start-up. To point at a daemon elsewhere, pass --daemon-url http://host:port (or --port 7801 for localhost) and set NULLPRINT_API_KEY. Resolution order, most explicit first:

--daemon-url / --port
NULLPRINT_DAEMON_URL
NULLPRINT_PORT
~/.nullprint/daemon.json (NULLPRINT_HOME changes the directory)

If the daemon is not running the tools say so plainly instead of throwing a connection trace.

Tools

Tool	What it does	Daemon endpoint
`profiles_list`	List every profile with status (running / idle), exit and ledger metadata	`GET /profiles`
`profile_start`	Open a browser session for a profile; returns the driving endpoints	`POST /sessions/{name}`
`profile_stop`	Stop that profile's browser (session or app-launched window)	`DELETE /sessions/{name}` → falls back to `POST /profiles/{name}/stop`
`profile_create`	Create a profile (fingerprint generated and frozen), optionally with proxy, ledger and start pages	`POST /profiles`
`profile_checkup`	Consistency check-up, returns `{summary, checks}`	`GET /profiles/{name}/checkup?live=`
`proxy_check`	Stateless proxy test: exit IP, country, latency	`POST /proxy-check`
`profile_delete`	Soft delete to the recycle bin (recoverable); refused while running	`DELETE /profiles/{name}`
`trash_list`	Read-only list of recoverable profiles in the recycle bin	`GET /trash`
`profile_restore`	Restore from the recycle bin with fingerprint, proxy and logins intact	`POST /trash/{name}/restore`
`session_goto`	Navigate the session's current page	`POST /sessions/{name}/goto`
`session_snapshot`	Accessibility tree of the current page (find selectors, read state)	`GET /sessions/{name}/snapshot`
`session_click_selector`	Click an element by CSS selector	`POST /sessions/{name}/click_selector`
`session_fill_selector`	Fill an input by CSS selector	`POST /sessions/{name}/fill_selector`
`session_press`	Send a key (e.g. `Enter`)

Notes that matter when writing prompts:

session_* tools need an open session. They drive the warm session opened by profile_start; calling them on a profile without one returns 409. Selectors are CSS, not XPath or role/name; call session_snapshot first when you do not know a selector.
session_eval returns an envelope. A page-side JavaScript error comes back as data ({ok: false, error, error_type}), not as a tool failure; result follows the expression's type.
profile_stop has two levels. A profile can be "running" as a warm session or as a window launched from the app. The tool tries the session first and falls back to the app-level stop, which is idempotent for idle profiles. It returns {name, stopped, closed}.
profile_create does not hard-code a kernel. Leave engine empty to use the app's default; unknown values come back as a 422 listing the options.
proxy_check failures are data. An unreachable proxy returns {ok: false, error}; only an unreachable daemon raises.
profile_start returns cdp_endpoint (a ws:// DevTools address) for Chrome kernels, so external tools can attach. A session driven from outside bypasses Nullprint's consistency guards: an outside tool can set a viewport, language or time zone that contradicts the profile's frozen fingerprint and make it detectable. Prefer the session_* tools; if you must attach, do not change anything the profile has not declared.

What is deliberately not exposed

Permanently deleting a profile (DELETE /trash/{name}) destroys its logins and cannot be undone. It is not a tool on purpose: emptying the recycle bin is a human action in the desktop app. profile_delete's description tells the agent to say so instead of working around it, and a test scans every tool's source to keep the purge endpoint out. Screenshot-to-disk and file-writing tools are left out for the same reason (local path safety).

Development

Terminal

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

Tools live in nullprint_mcp/tools.py (the TOOLS tuple); server.py and __main__.py do not change when a tool is added. Nothing may be printed to stdout: stdout is the MCP channel.

License

中文说明

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

前提：本机装好并登录 Nullprint 桌面应用；本机有 Python 3.11+，推荐用 uv（首次运行自动装包）。

接入：

Terminal

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。

17 个工具：profiles_list、profile_start、profile_stop、profile_create、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 再用）。彻底删除身份故意不做成工具：清空回收站只能在桌面应用里由人操作。