zevian-mcp

Zevian for AI coding agents

zevian-mcp connects your AI coding agent (Claude Code, Cursor, VS Code) to Zevian. Ask your agent to audit your site, check a page on localhost before you deploy it, and fix what it finds, all without leaving your editor.

• Audit a connected site, or one page of it, and read the issues (errors, warnings and info).
• Check a page before you deploy. Your agent fetches localhost, staging or any unpublished page from your machine and Zevian analyzes it. Zevian never fetches your localhost.
• Fix it two ways. Get exact instructions your agent applies in your own repository, or have Zevian's GitHub App open a pull request for you.
• See what the fixes achieved in Search Console and Bing.

Set up in three minutes

You need Node.js 20 or newer and a Zevian account.

• Create an API key. In the Zevian dashboard, open Connect to your AI agent (or go to app.zevian.tech/settings/api), name the key, and choose Read or Read + write. Copy it: it is shown once. Read + write is only needed to let the agent open pull requests.
• Add Zevian to your agent. Replace zv_live_YOUR_KEY with your key. The dashboard shows each of these with your key already filled in.

Claude Code

macOS, Linux and WSL:

claude mcp add --env ZEVIAN_API_KEY=zv_live_YOUR_KEY --transport stdio zevian -- npx -y zevian-mcp

Windows (PowerShell or cmd):

claude mcp add --env ZEVIAN_API_KEY=zv_live_YOUR_KEY --transport stdio zevian -- cmd /c npx -y zevian-mcp

Then start Claude Code and type /fix-seo, or ask it to audit your site with Zevian.

Cursor

Save this as .cursor/mcp.json in your project, or ~/.cursor/mcp.json to use it everywhere:

{
  "mcpServers": {
    "zevian": {
      "command": "npx",
      "args": [
        "-y",
        "zevian-mcp"
      ],
      "env": {
        "ZEVIAN_API_KEY": "zv_live_YOUR_KEY"
      }
    }
  }
}

Add the file to .gitignore if it is in your project, so the key is not committed. Then make sure Zevian is switched on under Customize in the sidebar.

VS Code

Save this as .vscode/mcp.json in your project, or run MCP: Open User Configuration to use it everywhere:

{
  "servers": {
    "zevian": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "zevian-mcp"
      ],
      "env": {
        "ZEVIAN_API_KEY": "zv_live_YOUR_KEY"
      }
    }
  }
}

Add the file to .gitignore if it is in your project, so the key is not committed. Then start the server from the Zevian entry in the file, trust it when VS Code asks, and ask in the Chat view with an agent, so it can call Zevian's tools.

Try it

Three things to ask your agent:

• "Audit my site with Zevian and fix the errors and warnings." (Or type /fix-seo.) The agent finds your site, runs an audit, shows you what is wrong, and applies each fix in your repository.
• "Check http://localhost:3000/pricing with Zevian before I deploy." The agent fetches the page from your machine, Zevian lists the problems with their fixes, and the agent can apply them.
• "Open a pull request that fixes the schema issues from that audit." The agent shows you which issues it will fix and waits for your yes, then Zevian's GitHub App opens one pull request.

Tools

Your agent picks these itself. Each one tells the agent when to use it.

Tool	Use it to	Reads or changes
list_sites	List your connected sites. The agent calls this first, to get a site_id.	Reads
run_audit	Audit a site (scope: "full") or one page of it (scope: "page", with url). Waits about 45 seconds, then returns an audit_id to follow up with get_audit.	Starts a crawl; changes nothing on your site
get_audit	Read an audit: status, scores, and issues worst first, filtered by severity (error, warning, info) or category (seo, geo, aeo, schema).	Reads
get_fix	Get instructions for fixing one issue: the kind of change, which files to look in, exact target values and limits. Instructions, not a diff.	Reads
open_fix_pr	Open one pull request that fixes 1 to 20 issues. The agent asks you to confirm first. Waits about 45 seconds, then returns a pr_id. Needs a Read + write key.	Changes your repository
get_fix_pr	Check a pull request started by open_fix_pr: its status, its URL once open, and why it failed if it did.	Reads
check_page	Check one page, including localhost and staging. Returns the page's issues, each with its fix.	Reads
get_impact	Search Console and Bing performance, and the before and after of each merged Zevian pull request. Paid plans.	Reads

And one prompt, fix-seo (a slash command in Claude Code and similar agents), which audits the site, shows you the errors and warnings, applies each fix in the current repository, and summarizes what changed. It takes an optional domain.

What check_page sends, and what it never does

check_page fetches the page from your machine, follows redirects, waits up to 15 seconds, and reads at most 2 MB of HTML. Then it sends Zevian the page's URL, status, HTML and response headers, so Zevian can analyze it. In that step:

• No cookies, ever. The request to your page carries no Cookie or Authorization header, and nothing is stored between calls.
• Credentials are removed before anything leaves your machine. The response headers Set-Cookie, Cookie, Authorization and Proxy-Authorization are dropped, and so is any header whose name contains token, secret, session or key. Zevian only reads the content type, X-Robots-Tag and Link.
• Zevian never fetches your page. It reads only what the package sends. It does not follow links in your HTML or load anything your HTML points to.
• The HTML itself is sent as served. Do not check a page that shows private data you do not want analyzed.
• Only the HTML as served is checked, so content a browser draws with JavaScript is not visible. The result says so when a page is mostly empty before JavaScript runs.

Your API key goes only to Zevian, in the Authorization header, and is never printed or logged.

Plans and limits

	Free	Pro and Team
check_page	20 a day	500 a day
run_audit	3 a day	50 a day
get_fix	10 a day	300 a day
open_fix_pr	1 a month, shared with the dashboard	The plan's monthly pull request limit, shared with the dashboard
get_impact	Not included	Included

Daily limits reset at 00:00 UTC. When you hit one, the message says when it resets and where to upgrade.

Configuration

Variable
ZEVIAN_API_KEY	Required. Your key, from the dashboard. Without it the server still starts, and every tool tells the agent how to create one.
ZEVIAN_API_URL	Optional. Defaults to https://app.zevian.tech. Use it to point at staging. It must be https://, except for http://localhost, so your key is never sent unencrypted.

Every request carries a User-Agent of the form zevian-mcp/<version>, so Zevian can tell you when a newer version is available.

Troubleshooting

The messages come from Zevian and say what to do. The common ones:

Message	What to do
Zevian API key missing. Create one at zevian.tech/settings/api	Set ZEVIAN_API_KEY in your agent's config for Zevian.
This API key is invalid or revoked. Create a new one in the dashboard	Make a new key and replace the old one.
This key is read-only. Create a key with write access to open PRs	Make a Read + write key.
Zevian GitHub App isn't installed on this repo. Install it here: …	Open the link and install the app on the repository.
Couldn't reach this URL. If it's localhost, is your dev server running?	Start your dev server and try again.
Plan limit reached for today …	Wait for 00:00 UTC, or upgrade.

If claude mcp add says Invalid environment variable format, the server name is directly after --env. Keep the command as shown, with --transport stdio between them: --env takes several values and would read the name as one.

On native Windows, older versions of Claude Code could not start npx without cmd /c in front of it. Current versions can, and the Windows command above works on both.

For developers

npm install
npm test          # builds, then runs the unit and stdio integration tests
npm run lint

The server speaks MCP over stdio. It writes only protocol messages to stdout; logs go to stderr. Built with the official MCP TypeScript SDK (@modelcontextprotocol/server).