# @openweb-dev/mcp-server

MCP server for [OpenWeb](https://github.com/songzeli/openweb) — the booking-grade reliability layer for AI agents.

Adds tools to your AI assistant (Claude Desktop, Cursor, etc.) for completing real bookings on the open web: restaurant reservations, event registrations, clinic appointments. Recipe-replay engine + unattended SMS verification via Twilio. ~95% reliability at ~$0.03/booking on validated platforms (SevenRooms, Eventbrite, Lu.ma, Solv, Resy).

## Two ways to use it

| | Free (local) | Paid (hosted brain) |
|---|---|---|
| **Install** | `git clone` + `docker-compose up` + Anthropic key | `npx @openweb-dev/mcp-server` + 2 env vars |
| **Pays** | Your own Anthropic spend | Per-call to brain operator |
| **Recipes** | Private to your machine | Shared corpus across paid-tier customers |
| **Setup time** | ~5 min | ~30 seconds |

## Quickstart — hosted brain (recommended for non-developers)

Get a brain key from the maintainer (DM the issue or post in discussions), then add this to your Claude Desktop config:

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```jsonc
{
  "mcpServers": {
    "webmcp": {
      "command": "npx",
      "args": ["-y", "@openweb-dev/mcp-server"],
      "env": {
        "OPENWEB_BRAIN_URL": "https://webmcp-brain.fly.dev",
        "OPENWEB_BRAIN_KEY": "sk_live_…",
        "OPENWEB_PROFILE_PATH": "/abs/path/to/.profile"
      }
    }
  }
}
```

Restart Claude Desktop. OpenWeb's tools (`book`, `provide_input`) are now available — try asking Claude to book a restaurant or RSVP to an event.

`OPENWEB_PROFILE_PATH` points at a JSON file with your contact info (first name, last name, email, phone, ...). See the [main repo's `.profile.example`](https://github.com/songzeli/openweb/blob/main/.profile.example) for the shape.

## Quickstart — local self-host (for developers, free)

```bash
git clone https://github.com/songzeli/openweb
cd openweb
docker-compose up -d postgres
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
pnpm install && pnpm -r build
pnpm migrate
```

Then point Claude Desktop config at the local-built MCP server:

```jsonc
{
  "mcpServers": {
    "webmcp": {
      "command": "node",
      "args": ["/abs/path/to/openweb/packages/mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://webmcp:webmcp_dev@localhost:5432/webmcp",
        "ANTHROPIC_API_KEY": "sk-ant-…",
        "OPENWEB_PROFILE_PATH": "/abs/path/to/.profile"
      }
    }
  }
}
```

Same MCP tools available; everything runs on your machine; nothing leaves your network.

## What this MCP server exposes

| Tool | What it does |
|---|---|
| `book` | Submit a booking task. The engine reads your profile, navigates the site, fills the form, handles verification (SMS via Twilio if configured), and submits. Returns booking ID + status. |
| `provide_input` | Resume a paused booking with user-supplied data (e.g. an OTP code if Twilio auto-resolution isn't set up). |
| `discover` | Search OpenWeb's knowledge base for sites/platforms it knows. |

See the [main repo](https://github.com/songzeli/openweb) for the full feature catalog: 5 validated platforms, ~40 named failure modes each with a shipped fix, 870+ unit tests.

## Architecture (one diagram)

```
Claude Desktop ──► @openweb-dev/mcp-server (this package, runs on YOUR machine)
                          │
                          ▼
                   @openweb-dev/engine (bundled in)
                          │
              ┌───────────┴───────────┐
              ▼                       ▼
     local Chromium           https://webmcp-brain.fly.dev
     (Playwright)             (LLM + recipe corpus)
                              [only if OPENWEB_BRAIN_URL set]
```

The MCP server runs as a local subprocess on your machine. Web browsing happens locally via Playwright. LLM calls go either to your own Anthropic key (free local mode) or to the hosted brain (paid mode, set via 2 env vars).

## Links

- **Repo / source / issues**: https://github.com/songzeli/openweb
- **Strategy + roadmap**: https://github.com/songzeli/openweb/blob/main/docs/PLAN.md
- **Closed-gap catalog (the moat)**: https://github.com/songzeli/openweb/blob/main/docs/archive/CLOSED_GAPS.md
- **License**: MIT
