# browse2mcp

Turn any website into an MCP server. Browse a site, and browse2mcp records the API traffic and generates a fully working MCP server with tools for every endpoint it sees.

## How it works

1. **Record** — Opens a browser, you use the site normally, and it captures all API requests
2. **Generate** — Analyzes the captured traffic and produces a TypeScript MCP server with one tool per endpoint
3. **Use** — Connect the generated server to Claude Desktop (or any MCP client) and interact with the API through natural language

browse2mcp handles REST and GraphQL, detects auth patterns, bakes in captured tokens for zero-config usage, and includes a `login` tool so you can refresh expired tokens without re-recording.

## Install

```bash
git clone https://github.com/danielthedm/browse2mcp.git
cd browse2mcp
npm install
npx playwright install chromium
```

## Quick start

### 1. Record a session

```bash
npx tsx bin/browse2mcp.ts record https://app.example.com -o my-session.json
```

A browser opens. Use the site — click around, load data, interact with features. When you're done, close the browser. All API traffic is saved to the session file.

**Options:**

| Flag | Description |
|------|-------------|
| `-o, --output <path>` | Output session file (default: `session.json`) |
| `-p, --profile <name>` | Persistent browser profile — logins are saved between sessions |
| `-c, --connect <port>` | Connect to a running Chrome instance on this debug port |
| `-v, --verbose` | Verbose logging |

### 2. Generate an MCP server

```bash
npx tsx bin/browse2mcp.ts generate my-session.json -o my-mcp --name my-server --full
```

This analyzes the recorded traffic, generates a TypeScript MCP server, installs dependencies, builds it, and prompts you to add it to your Claude Desktop config.

**Options:**

| Flag | Description |
|------|-------------|
| `-o, --output <path>` | Output directory (with `--full`) or file path (default: `mcp-server.ts`) |
| `--full` | Generate a full project with `package.json`, `tsconfig.json`, etc. |
| `--name <name>` | Server name (default: `my-mcp-server`) |
| `--refine` | Force LLM refinement of tool descriptions (requires `ANTHROPIC_API_KEY`) |
| `--no-refine` | Skip LLM refinement |
| `-v, --verbose` | Verbose logging |

### 3. Use it

After generation, the tool offers to add the server to your Claude Desktop config automatically. Restart Claude Desktop and the tools are available immediately.

## What gets generated

- **One tool per endpoint** — REST endpoints get `list_users`, `get_user`, `create_post`, etc. GraphQL operations use the operation name (`get_users`, `create_user`)
- **Auth handling** — Detected auth tokens are baked in. A `login` tool lets you open a browser and re-authenticate when tokens expire
- **Token persistence** — Fresh tokens from the `login` tool are saved to `~/.browse2mcp/tokens/` and used automatically
- **Zero config** — Generated servers work out of the box with no environment variables needed

## Auth token priority

When auth is detected, the generated server resolves tokens in this order:

1. Persisted token file (`~/.browse2mcp/tokens/<server-name>.json`) — written by the `login` tool
2. Environment variable (e.g. `API_TOKEN`)
3. Baked-in token captured during recording

## Examples

### Record and generate from any web app

```bash
# Record
npx tsx bin/browse2mcp.ts record https://app.example.com -o my-session.json -p my-app

# Generate
npx tsx bin/browse2mcp.ts generate my-session.json -o my-mcp --name my-app --full
```

### Use a persistent browser profile

```bash
npx tsx bin/browse2mcp.ts record https://app.example.com -p my-profile
```

The `-p` flag saves browser state (cookies, localStorage) to `~/.browse2mcp/profiles/my-profile/`. Next time you record with the same profile, you'll already be logged in.

### Connect to an existing Chrome

```bash
# Start Chrome with remote debugging
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Connect browse2mcp to it
npx tsx bin/browse2mcp.ts record https://app.example.com -c 9222
```

## Development

```bash
npm test            # Run tests
npm run test:watch  # Watch mode
npm run build       # Compile TypeScript
```

## License

MIT