ghostcrawl-mcp-server 2.2.0

MCP server for GhostCrawl — managed browser automation via Claude Desktop and agent runtimes

ghostcrawl-mcp-server

MCP server for GhostCrawl — managed browser automation via Claude Desktop and agent runtimes.

ghostcrawl-mcp-server exposes 8 tools (start, end, navigate, act, observe, extract, screenshot, network) over the Model Context Protocol so Claude Desktop, Cursor, and cloud agent runtimes can drive GhostCrawl's managed browser engines. Tool names follow the canonical GhostCrawl agent vocabulary; screenshot and network are GhostCrawl additions over the six-primitive baseline. Capability profiles let operators ship a narrower tool surface to clients that only need a subset — see GHOSTCRAWL_MCP_CAPABILITIES.

---

Quick Start — stdio (Claude Desktop / local agents)

The fastest way to get started is uvx, which installs and runs the server in one command without polluting your Python environment:

uvx ghostcrawl-mcp-server

Or with explicit stdio transport flag:

uvx ghostcrawl-mcp-server --stdio

Set GHOSTCRAWL_API_KEY and GHOSTCRAWL_API_URL in your shell or via the Claude Desktop config (see below).

---

Claude Desktop Configuration (stdio)

Add this block to your Claude Desktop config file (claude_desktop_config.json):

{
 "mcpServers": {
 "ghostcrawl": {
 "command": "uvx",
 "args": ["ghostcrawl-mcp-server"],
 "env": {
 "GHOSTCRAWL_API_KEY": "your-key-here",
 "GHOSTCRAWL_API_URL": "http://localhost:8080"
 }
 }
 }
}

Step-by-step walkthrough: See docs/claude-desktop-config.md.

---

Quick Start — HTTP (cloud agent runtimes)

Run the server over streamable-HTTP for cloud agent runtimes:

uvx ghostcrawl-mcp-server --http --port 8090

Or run standalone for local testing:

docker build -t ghostcrawl-mcp-server ghostcrawl-mcp-server/
docker run -p 8090:8090 \
 -e GHOSTCRAWL_API_URL=http://localhost:8080 \
 -e GHOSTCRAWL_API_KEY=your-key \
 ghostcrawl-mcp-server

Once running, point Cursor / Continue.dev / any MCP-capable agent at:

{
 "mcpServers": {
 "ghostcrawl": {
 "type": "http",
 "url": "http://localhost:8090/mcp"
 }
 }
}

Full SSE/HTTP setup guide: See docs/sse-http-config.md.

---

Tool Reference

All 8 tools are registered automatically when the server starts. Each tool call is routed to the ghostcrawl REST API (GHOSTCRAWL_API_URL) or debug sidecar (GHOSTCRAWL_SIDECAR_URL).

Tool	Key Inputs	Description
start	profile_id?: string	Start a browsing session. Pins a profile to this MCP connection. If profile_id is omitted, a fresh profile is minted automatically.
end	(none)	End the current session and release the pinned profile.
navigate	url: string	Navigate the active browser profile to a URL.
act	action: string	Perform a natural-language browser action (click, type, submit, etc.) via the agent executor.
observe	instruction: string	Observe the current page state and return a structured description.
extract	instruction?: string, schema?: object	Extract structured data from the current page. Pass a JSON Schema via schema for typed output.
screenshot	full_page?: bool, selector?: string	Capture a screenshot of the current page (or a CSS selector). Returns base64-encoded PNG via the debug sidecar.
network	filter?: string, since?: timestamp	Return recent network events captured by the browser sidecar. Optionally filter by URL pattern or start timestamp.

---

Configuration

Variable	Default	Description
GHOSTCRAWL_API_URL	http://localhost:8080	ghostcrawl REST API base URL
GHOSTCRAWL_SIDECAR_URL	http://localhost:8081	ghostcrawl debug sidecar base URL (screenshot/network)
GHOSTCRAWL_API_KEY	(empty)	Bearer token forwarded to ghostcrawl API. Never logged or echoed.

In the fleet compose stack, GHOSTCRAWL_API_URL defaults to http://ghostcrawl-api-master:8001 and GHOSTCRAWL_SIDECAR_URL defaults to the same address (the sidecar endpoints live in the same FastAPI app in the current fleet deployment).

---

Demo

A live screen-capture recording and raw JSONL session transcript are in docs/demo/ (populated in coming soon).

---

Development

cd ghostcrawl-mcp-server
pip install -e ".[dev]"
pytest tests/ -x -q

The test suite (53 tests) covers tool schemas, session pin/isolation, both stdio and streamable-HTTP transports, and packaging validation. All tests use mock REST servers (real TCP sockets, not respx patches) for process-boundary correctness.

---

Packaging

• Distribution name: ghostcrawl-mcp-server
• Entry point: ghostcrawl-mcp-server (console_scripts → ghostcrawl_mcp_server.cli:main)
• Dependencies: mcp==1.27.1, httpx>=0.28,<1
• uvx ghostcrawl-mcp-server works out of the box — no local Python install required.
• Pin with uv for reproducible lockfile.