Model Context Protocol server for Ceraph — run frontend test flows from Claude Code, Cursor, Codex, Windsurf, and other MCP-compatible AI coding tools.

Ceraph runs Playwright flows against your app to verify code changes work end-to-end. This package exposes Ceraph's test runner over the Model Context Protocol so your AI assistant can run tests, read results, and iterate without leaving the chat.

Requirements

Node.js >= 20
A repository hosted on GitHub
A Ceraph account (free trial available at https://ceraph.dev)

Install

npm install -g @ceraph/mcp

Or run on demand via npx:

npx -y @ceraph/mcp

Register with your AI tool

Add this to your MCP config (e.g. .mcp.json for Claude Code, or ~/.cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "ceraph": {
      "command": "npx",
      "args": ["-y", "@ceraph/mcp"]
    }
  }
}

Then restart your AI tool. The next time you ask it to test changes, it will call ceraph_init to set up the repo (GitHub OAuth device flow — surface the verification URL + code to the user, then call ceraph_init again to resume).

Tools exposed

Tool	Use it when
`ceraph_init`	First call in a repo with no `ceraph.config.js`. Idempotent.
`ceraph_test_changes`	Uncommitted edits — "test my changes."
`ceraph_test_file`	Specific files just edited. Accepts a single path or an array.
`ceraph_test_pr`	A PR number is in scope. Server-side run by default; `local: true` for fast Tier 0.
`ceraph_test_flow`	Debug one named flow.
`ceraph_test_all`	Full sweep. Expensive — only on explicit request.
`ceraph_dry_run`	Preview planned flows without running Playwright.
`ceraph_pr_status`	Poll a server-side PR run for completion.
`ceraph_skip` / `ceraph_mobile`	Toggle the `ceraph-skip` / `ceraph-mobile` PR labels.
`ceraph_config`	Read/write user preferences (`skipDraftPrs`, `autoTestOptedOut`, `maxLocalRuns`).
`ceraph_test_data_list`	List managed test users.
`ceraph_test_data_health`	Audit managed test users against current schema/graph.
`ceraph_test_data_provision`	Provision auth credentials for the flows touched by a PR/diff/files.
`ceraph_test_data_cleanup`	Delete a managed test user.