@logistn/hidemium-mcp

MCP servers for the Hidemium platform. Lets AI agents (Claude Code, Codex, Cursor, Antigravity, opencode) and the Hidemium app's built-in AI drive Hidemium browsers, profiles, scripts, campaigns, schedules and proxies directly from chat.

What you get

| Server | Command | Tools | |---|---|---| | Management | hidemium-mcp | ~58 tools — profiles, scripts + store, folders, campaigns, schedules, worklogs, nodes, proxies, auto-delete, plan info | | Automation | hidemium-mcp automation | ~28 tools — humanized browser control over CDP: navigate, ARIA snapshot, click/type/scroll/fill/drag/hover, forms, file upload, video watching, feed navigation, dialogs, tabs, network/console |

The skills (hidemium-automation, hidemium-management) ship inside the package and are exposed by both servers as MCP resources (skill://...) — no extra files to install or place anywhere.

Requirements

• Hidemium app v4 running locally (API on 127.0.0.1:2222, CDP enabled) — or any server reachable via HIDEMIUM_API_HOST/HIDEMIUM_API_PORT.
• Node.js ≥ 20 with npx.

No environment variables are required — defaults point to a stock local Hidemium install.

Quick start

Option A — auto-setup with the bundled CLI (recommended)

# Writes entries into every client config that already exists:
#   ~/.codex/config.toml (Codex), ./.mcp.json (Claude Code, project scope),
#   ~/.cursor/mcp.json (Cursor), ~/.gemini/config/mcp_config.json (Antigravity),
#   ~/.config/opencode/opencode.json (opencode)
npx -y @logistn/hidemium-mcp install

# Show which clients already have the entries
npx -y @logistn/hidemium-mcp check

# Remove the entries again
npx -y @logistn/hidemium-mcp remove

install only appends to configs that already exist — it never creates new files. Server entries resolve the latest published version via npx -y, so updates are automatic (restart the client to pick them up).

Option B — per agent (official configuration)

Claude Code

The official way is the claude mcp add command (run inside your project for project scope, or with -s user for user scope):

claude mcp add hidemium -- npx -y @logistn/hidemium-mcp
claude mcp add hidemium-automation -- npx -y @logistn/hidemium-mcp automation

Project-scoped alternative: .mcp.json in the project root (committable, shared with the team):

{
  "mcpServers": {
    "hidemium": { "command": "npx", "args": ["-y", "@logistn/hidemium-mcp"] },
    "hidemium-automation": { "command": "npx", "args": ["-y", "@logistn/hidemium-mcp", "automation"] }
  }
}

Verify with claude mcp list. Restart Claude Code after adding.

Codex

Edit ~/.codex/config.toml (the official Codex config location):

[mcp_servers.hidemium]
command = "npx"
args = ["-y", "@logistn/hidemium-mcp"]

[mcp_servers.hidemium-automation]
command = "npx"
args = ["-y", "@logistn/hidemium-mcp", "automation"]

Cursor

Global: ~/.cursor/mcp.json (all projects) — or project-level .cursor/mcp.json. You can also use the UI: Settings → MCP → + Add new MCP server.

{
  "mcpServers": {
    "hidemium": { "command": "npx", "args": ["-y", "@logistn/hidemium-mcp"] },
    "hidemium-automation": { "command": "npx", "args": ["-y", "@logistn/hidemium-mcp", "automation"] }
  }
}

Restart Cursor after saving.

Antigravity (Google — formerly Windsurf)

Use the UI: in the agent side panel click … → MCP Servers → Manage MCP Servers → View raw config (opens the correct mcp_config.json), then add:

{
  "mcpServers": {
    "hidemium": { "command": "npx", "args": ["-y", "@logistn/hidemium-mcp"] },
    "hidemium-automation": { "command": "npx", "args": ["-y", "@logistn/hidemium-mcp", "automation"] }
  }
}

The global config lives at ~/.gemini/config/mcp_config.json (workspace-scoped alternative: .agents/mcp_config.json in the project root). Restart Antigravity after saving.

opencode

Edit ~/.config/opencode/opencode.json (or project opencode.json):

{
  "mcp": {
    "hidemium": { "type": "local", "command": ["npx", "-y", "@logistn/hidemium-mcp"], "enabled": true },
    "hidemium-automation": { "type": "local", "command": ["npx", "-y", "@logistn/hidemium-mcp", "automation"], "enabled": true }
  }
}

Verify the servers standalone

npx -y @logistn/hidemium-mcp            # management server — logs tool registration, ~58 tools
npx -y @logistn/hidemium-mcp automation # automation server — ~28 tools

Environment variables

All optional — defaults work with a stock local Hidemium install.

| Variable | Default | Description | |---|---|---| | HIDEMIUM_API_HOST | 127.0.0.1 | Local Hidemium API host | | HIDEMIUM_API_PORT | 2222 | Local Hidemium API port | | HIDEMIUM_API_TOKEN | — | Bearer token (required once the app has auth enabled) | | HIDEMIUM_API_TIMEOUT_MS | 90000 | HTTP timeout | | HIDEMIUM_API_MAX_RETRIES | 3 | Retries for read-only requests | | HIDEMIUM_MCP_SNAPSHOT_MODE | auto | auto = snapshot attached to tool results · none = text results only | | HIDEMIUM_MCP_MAX_CONNECTS | 3 | Max parallel CDP connections |

Capabilities

• Management (58 tools) — profile CRUD + open/close, scripts + store, folders, campaigns, schedules, worklogs, nodes, proxies, auto-delete, plan info.
• Automation (28 tools) — connect profiles over CDP, navigate, ARIA snapshots, click/type/fill/drag/scroll/hover (humanized), dialogs, file upload, video watching, feed navigation, JS evaluate, tabs, network/console.

Automation tools are snapshot-first: results carry element refs, so the agent never needs to guess selectors.

Troubleshooting

| Symptom | Fix | |---|---| | Tools not visible in the client | Restart the client after config change; run npx -y @logistn/hidemium-mcp check to confirm the entry exists | | Stale tool list after an update | npx -y caches downloads — clear ~/AppData/Local/npm-cache/_npx (Windows) or ~/.npm/_npx (macOS/Linux) and restart | | ECONNREFUSED on :2222 | Hidemium app not running or API on a different port — set HIDEMIUM_API_PORT | | Profile opens but browser actions fail | Ensure the app has CDP enabled for profiles (automation requires the local app, not just the cloud API) |

License

MIT