vConsole MCP

English | 简体中文

注意事项： vConsole 官方不提供 MCP 链接能力，请使用 https://github.com/Simonmie/vConsole/tree/dev 中的代码尝试。

Note: Official vConsole does not provide MCP connectivity. To try this integration, use the code from the linked dev branch above.

Expose console logs, network requests, and explicitly authorized JavaScript execution from a mobile H5 page to MCP clients such as Codex and Claude Code.

flowchart LR
    Agent["Codex / Claude Code"] <-->|"MCP stdio"| MCP["vconsole-mcp"]
    MCP <-->|"WebSocket :8765"| Mobile["Mobile H5 + vConsole"]
    Mobile --> Data["Console / Network stores"]

Loading

Records stay in the mobile page and are read on demand; the MCP process does not need a database or cloud service.

Development

pnpm install
pnpm build
node dist/index.js

The process uses stdio for MCP and listens for mobile WebSocket connections on 0.0.0.0:8765 by default. Startup messages are written to stderr so the MCP transport remains valid.

Options can be passed as arguments or environment variables:

node dist/index.js --host 0.0.0.0 --port 8765
VCONSOLE_MCP_HOST=0.0.0.0 VCONSOLE_MCP_PORT=8765 node dist/index.js

An optional pairing token prevents other pages from registering with the local bridge:

node dist/index.js --token your-development-token
VCONSOLE_MCP_TOKEN=your-development-token node dist/index.js

Install in an MCP client

Build the project first, then register the absolute entry path.

codex mcp add vconsole -- node /Users/jiangkexian/Desktop/MCP/vConsole-MCP/dist/index.js
claude mcp add vconsole -- node /Users/jiangkexian/Desktop/MCP/vConsole-MCP/dist/index.js

With a pairing token, pass the same value to the MCP process and the mobile page:

codex mcp add vconsole --env VCONSOLE_MCP_TOKEN=your-development-token -- node /Users/jiangkexian/Desktop/MCP/vConsole-MCP/dist/index.js

After publishing the package, clients can use:

codex mcp add vconsole -- npx -y vconsole-mcp
claude mcp add vconsole -- npx -y vconsole-mcp

Only one MCP process can listen on port 8765 at a time. Run either Codex or Claude Code, or assign different ports when using both concurrently.

Tools

• list_pages: list connected mobile pages.
• get_console_logs: read recent console records with optional level filtering.
• get_network_requests: read recent network records with optional failure, URL, body, and limit filters.
• execute_javascript: execute up to 100,000 characters of JavaScript in the page selected by its required pageId through runtime.evaluate. It requires explicit authorization from the mobile user in vConsole before the code runs. Arbitrary code may mutate page state or storage, expose sensitive data, and send network requests. The optional timeout is between 100 and 30,000 milliseconds and defaults to 8,000.

For the read tools, pageId is optional when one page is connected. execute_javascript always requires a pageId; call list_pages first to select the intended target.

The first three tools are read-only. execute_javascript is marked non-read-only, potentially destructive, non-idempotent, and open-world because arbitrary page code can change application state and communicate with external systems. It is the only execution capability exposed by this MCP package; no separate DOM, click, input, storage, or clear tools are provided.

Mobile connection

Initialize the forked vConsole with an endpoint:

const vConsole = new VConsole({
  mcp: {
    endpoint: 'ws://192.168.1.100:8765',
    token: 'your-development-token',
    autoConnect: true,
    allowJavaScriptExecution: false,
  },
});

Or connect later:

vConsole.mcp.connect('ws://192.168.1.100:8765');

JavaScript execution is denied by default. Enable Allow JavaScript Execution in the vConsole MCP panel for the current page. The panel permission resets after a page reload; trusted automated test pages may instead initialize vConsole with allowJavaScriptExecution: true.

Use the computer's LAN IP instead of localhost, keep the phone and computer on the same network, and allow the Node.js process through the computer firewall when prompted. This initial version is intended for trusted development networks and keeps all captured data in the mobile page. For an HTTPS H5 page, put the WebSocket endpoint behind a trusted WSS reverse proxy or relay; browsers block an HTTPS page from opening ws:// mixed content.