MCP 服务器

writ-mcp

Connects MCP clients to Writ, turning saved browser workflows into callable tools. Allows running workflows, retrieving data, scheduling, and more.

README

<br/>

<h3 align="center">Your saved browser workflows, as tools your assistant can call.</h3>

<p align="center"> <a href="#quick-start"><b>Quick start</b></a> · <a href="#tools-you-get"><b>Tools</b></a> · <a href="#configuration"><b>Configuration</b></a> · <a href="#security"><b>Security</b></a> · <a href="#troubleshooting"><b>Troubleshooting</b></a> · <a href="./CONTRIBUTING.md"><b>Contributing</b></a> </p> </div>

writ-mcp connects a stdio MCP client — Claude Code, Claude Desktop, Cursor, Windsurf, Codex — to Writ, so the browser workflows you already recorded become tools your assistant can call: run them, read the data they collected, search past results, schedule them, expose them as REST endpoints, and kick off site crawls.

It is a transparent stdio↔HTTP proxy and nothing else. Every tool, schema and rule lives server-side, so what you get always matches what your instance can do — and a new tool never requires upgrading this package. Zero dependencies, one file, Node core only.

Clients that speak Streamable HTTP natively don't need this at all — point them straight at the /mcp endpoint with an Authorization: Bearer <key> header.

Quick start

1. Get an API key. In the Writ app: Settings → Developers → API keys. Keys look like wt_….

2. Add the server.

Against a self-hosted coordinator:

claude mcp add writ-selfhost -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url https://writ.example.com

Against a coordinator on this machine:

claude mcp add writ-selfhost -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url http://localhost:8000

Against a published per-workflow endpoint (an "Expose as MCP" slug URL is used verbatim — no path rewriting):

claude mcp add my-tools -e WRIT_API_KEY=<YOUR_API_KEY> -- npx -y writ-mcp --url https://mcp.example.com/mcp/my-tools

3. Check it.

claude mcp list

Writ Cloud is the default target when you pass no --url (https://api.usewrit.app). The hosted service is not live yet — until it is, always pass --url pointing at your own coordinator. See Status.

Pass the key through the environment, not the command line. --api-key works, but it puts your key in the process's argument list where any local process can read it via ps, and your shell records it in history. The connector prints a note when you use it.

Your running coordinator also hands out these one-liners, pre-filled, on its Connect page and at GET /api/mcp/connect-info:

Claude Desktop / Cursor (config file)

Add to claude_desktop_config.json (Claude Desktop) or ~/.cursor/mcp.json (Cursor). The env form is recommended — it keeps the key out of the argument list:

{
  "mcpServers": {
    "writ-selfhost": {
      "command": "npx",
      "args": ["-y", "writ-mcp"],
      "env": {
        "WRIT_COORDINATOR_URL": "https://writ.example.com",
        "WRIT_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

Without npm

A self-host install bundles this connector at connectors/writ-mcp. There is no build step, so you can run it straight from disk:

node /path/to/writ/connectors/writ-mcp/index.js --url https://writ.example.com

It coexists with the other Writ servers. Each surface registers under its own slug on purpose — the desktop app is writ, Writ Cloud is writ-cloud, a self-hosted coordinator is writ-selfhost — and each identifies itself to the assistant with a distinct title. Keep any combination connected at once.

Tools you get

Served by the coordinator, not by this package:

Tool	What it does
`writ_list_workflows`	Your saved workflows — plus a `run_<name>` tool per workflow
`writ_run_workflow`	Run one and wait for the extracted data
`writ_workflow_data`	Read a workflow's accumulated data table
`writ_search_data`	Search across everything already collected
`writ_export_data`	Export a workflow's data as CSV/JSON
`writ_workflow_runs`	Run history and status
`writ_set_schedule`	Schedule a workflow (interval / daily / weekly)
`writ_expose_workflow_api`	Publish a workflow as a callable REST endpoint
`writ_crawl_site` / `writ_crawl_status`	Start and poll a distributed site crawl
`writ_create_automation`	Event → run-workflow / notify chains
`writ_create_monitor` / `writ_wire_monitor`	Watch a page and react to changes

A self-hosted coordinator additionally exposes writ_browser_use and writ_record_* — drive a live browser on your own fleet agent and save the session as a reusable workflow.

Reusing a recent result (`max_age`)

Running a workflow drives a real browser, so asking the same question twice in one session costs two full runs and two waits. Every workflow tool takes an optional max_age (seconds) meaning a recent answer is good enough:

{ "name": "run_price_check", "arguments": { "sku": "B0C123", "max_age": 300 } }

omitted or 0 — always run fresh (the default; nothing goes stale on its own).
N — reuse a result younger than N seconds, otherwise run.

A reused answer carries _cache: {hit: true, age_seconds: N} so the assistant can tell how current it is.

If a tool call times out

It comes back as status: "running" with retryable: true. The run was not cancelled — calling the tool again starts a second run. Wait, then retry with a max_age wide enough to pick up the first run's result once it lands.

Configuration

Flags take precedence over environment variables.

Flag	Env	Default	Purpose
`--url`	`WRIT_COORDINATOR_URL` / `WRIT_URL`	`https://api.usewrit.app`	Target base URL. A URL whose path is already `/mcp` or `/mcp/<slug>` is used verbatim.
`--api-key`	`WRIT_API_KEY`	— (required)	Key for `Authorization: Bearer`. Prefer the env var.
`--insecure`	`WRIT_INSECURE_TLS=1`	off	Accept a self-signed local-CA cert. Private networks only.
`--timeout`	`WRIT_MCP_TIMEOUT_MS`	`600000`	Per-request timeout (ms); covers long `writ_run_workflow` waits.
`--help` / `--version`	—	—	Print usage or version and exit.

HTTPS with a local CA (self-host): trust the CA (recommended) and use the https:// address, or set NODE_EXTRA_CA_CERTS=/path/to/ca.pem. Use --insecure only for localhost testing — it disables certificate verification entirely, which exposes your key to a man-in-the-middle.

Security

This process exists to carry a credential, so everything that could expose one is made loud rather than convenient. Full detail in SECURITY.md.

The key goes to --url and nowhere else. No telemetry, no analytics, no update check. Zero dependencies means there is no transitive code in the process that could phone home — and CI fails the build if that ever changes.
Redirects are never followed. Replaying your Authorization header to whatever origin a Location header names would hand your key to a host you didn't choose. A 3xx becomes an error telling you to point --url at the final URL.
Credentials in a URL are redacted from every diagnostic. MCP clients write a server's stderr to a log file on disk; https://user:pass@host/ would otherwise be written down in plaintext.
Loud warnings, on stderr, for every way a key leaks: TLS verification disabled, plaintext http:// to a non-loopback host, or a key passed on the command line.
Retries never double-run a workflow. Only read-only methods are retried; tools/call is sent exactly once, because a retry could re-execute a side effect the connector cannot see.
Responses are bounded at 32 MB, so a broken endpoint can't grow this process until the OS kills your session.
No request is ever left unanswered — a hung MCP client is a denial of service on your assistant, and that is the failure this connector works hardest to make impossible.

Scope your keys. Give a key only workflows:read / workflows:execute unless a tool you actually use needs more.

Verifying what you install

Releases are published from CI with npm provenance, so the tarball is cryptographically linked to the commit and workflow that built it:

npm audit signatures

Troubleshooting

Symptom	Cause and fix
`Unauthorized: … rejected the API key`	The key is wrong, disabled, or lacks scope. Recreate it under Settings → Developers with `workflows:read` / `workflows:execute`.
`Cannot reach …`	Wrong `--url`, or the target is down. For a self-signed cert see the local-CA note above.
`… redirected (HTTP 301)`	Your reverse proxy redirects (usually `http` → `https`). Point `--url` at the final URL.
`The API key contains characters that cannot be sent in an HTTP header`	A newline or control character got into the key — usually a copy-paste artifact. Re-copy it.
No tools listed	You have no saved workflows yet, or the key can't read them. The static `writ_*` tools appear regardless.
Client won't connect, no error	Read the connector's stderr — your client logs it. Claude Code: `~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-<name>/`.

Status


Self-hosted coordinator	Supported and verified end to end.
Published `/mcp/<slug>` endpoints	Supported.
Writ Cloud (`https://api.usewrit.app`, the no-`--url` default)	Not live yet. The hosted service has not launched; the hostname does not resolve. Pass `--url` until it does.

Development

npm test

No dev dependencies — the suite uses Node's built-in node:test and drives the real index.js as a subprocess against a mock MCP server, exercising the same stdio path an MCP client uses. It runs in about six seconds. npm publish runs it automatically via prepublishOnly.

See CONTRIBUTING.md — note the two hard rules: zero dependencies, permanently, and no tool logic here.

The rest of Writ


usewrit/writ	The self-host coordinator — web UI, API, your data. Start here.
usewrit/writ-agent	The Rust fleet worker that does the actual browsing.
writ-mcp (this repo)	The MCP connector.

License

MIT — see LICENSE.

This package is deliberately permissive because it runs inside your MCP client, not inside the coordinator, so it has to be embeddable anywhere. The coordinator it talks to is AGPL-3.0-only; the two licenses are not interchangeable.