Metadata-Version: 2.5
Name: cf-browser-mcp
Version: 2.1.0
Summary: MCP Server with 17 browser tools for Claude Code — powered by Cloudflare Browser Run
Project-URL: Homepage, https://github.com/claude-world/cf-browser
Project-URL: Documentation, https://github.com/claude-world/cf-browser#readme
Project-URL: Repository, https://github.com/claude-world/cf-browser
Project-URL: Issues, https://github.com/claude-world/cf-browser/issues
Project-URL: Changelog, https://github.com/claude-world/cf-browser/blob/main/CHANGELOG.md
Author-email: Claude World <hello@claude-world.com>
License-Expression: MIT
License-File: LICENSE
Keywords: browser-rendering,claude-code,cloudflare,mcp,model-context-protocol,web-scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Requires-Dist: cf-browser<3,>=2.1.0
Requires-Dist: mcp[cli]<3,>=2.3.0
Provides-Extra: dev
Requires-Dist: build>=1.6; extra == 'dev'
Requires-Dist: mypy>=2.4; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.4; extra == 'dev'
Requires-Dist: pytest>=9; extra == 'dev'
Requires-Dist: ruff>=0.17; extra == 'dev'
Requires-Dist: twine>=7; extra == 'dev'
Description-Content-Type: text/markdown

# cf-browser-mcp

MCP server (built on the official `mcp` 2.x Python SDK) exposing **17 Cloudflare Browser Run tools** (formerly Browser Rendering) to Claude Code and other MCP clients. Requires Python 3.10+.

## Install

```bash
python -m pip install cf-browser-mcp
```

## Configure

Set `CF_BROWSER_MODE` explicitly when both credential pairs might exist.

| Mode | Credentials | Tools |
|---|---|---|
| `direct` | `CF_ACCOUNT_ID`, `CF_API_TOKEN` | 12 read/crawl tools |
| `worker` | `CF_BROWSER_URL`, `CF_BROWSER_API_KEY` | All 17 tools |

Use environment expansion so secrets do not live in a project file:

```json
{
  "mcpServers": {
    "cf-browser": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "cf_browser_mcp.server"],
      "env": {
        "CF_BROWSER_MODE": "${CF_BROWSER_MODE}",
        "CF_BROWSER_URL": "${CF_BROWSER_URL}",
        "CF_BROWSER_API_KEY": "${CF_BROWSER_API_KEY}"
      }
    }
  }
}
```

For Direct mode, replace the two Worker variables with `CF_ACCOUNT_ID` and `CF_API_TOKEN`. If both complete credential pairs exist and no mode is selected, startup fails instead of silently choosing one.

## Tools

Read/crawl tools:

- `browser_content`, `browser_markdown`, `browser_screenshot`, `browser_pdf`
- `browser_snapshot`, `browser_scrape`, `browser_json`, `browser_links`, `browser_a11y`
- `browser_crawl`, `browser_crawl_status`, `browser_delete_crawl`

Worker interaction tools:

- `browser_click`, `browser_type`, `browser_evaluate`
- `browser_interact`, `browser_submit_form`

MCP input schemas accept real arrays/objects for cookies, headers, HTTP Basic authentication, actions, fields, script/style tags, and JSON response schemas. JSON-encoded strings remain accepted for compatibility. Read and interaction tools expose page controls consistently; crawls include `cache_ttl`, depth, formats, Content Signals purposes, freshness filters, URL patterns, JSON options, and rendered controls. Full `goto_options`, `wait_for_selector`, and `viewport` objects are available alongside flattened conveniences, with ambiguous combinations rejected. Static mode rejects browser-only options; crawl status accepts string or non-negative integer cursors and current record filters.

Screenshot and PDF results are written with unpredictable names into a process-private directory. Paths exclude URL credentials, files use mode `0600`, quotas prevent unbounded accumulation, and the directory is removed when the MCP process exits normally (a process killed by a signal leaves its private `0700` directory in the system temp folder).

Validation, configuration and SDK errors (authentication, rate limits, transport failures) are returned to the client as tool errors with their message; unexpected internal errors are reported only as a generic tool failure.

## Troubleshooting

- Interaction returns 501: enable the Worker `BROWSER` binding.
- Interaction returns 404: redeploy the current Worker; `/health` should report `2.1.0`.
- A tool reports ambiguous or missing credentials (checked on the first tool call): set `CF_BROWSER_MODE=direct` or `worker` and that mode's two variables.
- Crawl wait returns a failed JSON status only for terminal crawl states; transport/auth errors remain typed errors instead of being mislabeled as job failures. A crawl that finished but whose results could not be fetched in time reports `status: "completed"` with `_timeout: true`.

See the [project README](https://github.com/claude-world/cf-browser#readme) for setup and the complete API contract.

## License

[MIT](https://github.com/claude-world/cf-browser/blob/main/LICENSE)
