SERP Lens MCP server

@serplens/mcp publishes SERP Lens as an MCP server. An AI client outside the app can then audit URLs, drive the SERP Lens browser, and read Search Console data. It speaks stdio, and your client starts it for you.

The server is bridge-first. With the desktop app running, tools execute inside it against live browser tabs and the rendered DOM. Close the app and 5 audit tools still answer through the SERP Lens Audit API, while the other 23 report that the app is needed.

You need Node.js 24.18 or later, a team API key on the Pro or Team plan, and the desktop app running for 23 of the 28 tools.

Create an API key

In the desktop app, go to Settings → API keys and choose Create key. Label it after the client, so you can rotate one client's key without breaking the others. The key is shown once, so copy it before closing the dialog.

Add the server to your client

Every client runs the same command, npx -y @serplens/mcp, and passes the key through the env block. Replace your-key-here with your key.

Each opens its editor with the entry filled in and prompts before writing anything. Swap the placeholder for your key after it lands.

Codex

The Codex CLI, the ChatGPT desktop app, and the IDE extension share ~/.codex/config.toml, so adding it once covers all three:

codex mcp add serplens --env SERPLENS_API_KEY=your-key-here -- npx -y @serplens/mcp

In the desktop app or IDE extension, open Settings → MCP servers → Add server, choose STDIO, and enter npx -y @serplens/mcp.

Claude Code

claude mcp add serplens --scope user --env SERPLENS_API_KEY=your-key-here -- npx -y @serplens/mcp

--scope user covers every project, and the Code tab in the Claude desktop app reads the same config. --scope project writes a .mcp.json your team shares. Keep the key out of it by referencing a variable instead: "SERPLENS_API_KEY": "${SERPLENS_API_KEY}".

Claude Desktop

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json, then restart:

{
	"mcpServers": {
		"serplens": {
			"command": "npx",
			"args": ["-y", "@serplens/mcp"],
			"env": {
				"SERPLENS_API_KEY": "your-key-here"
			}
		}
	}
}

The standalone CLI does not read this file. Run claude mcp add-from-claude-desktop to import it.

Cursor

Use the button above, or add the same mcpServers block to ~/.cursor/mcp.json. Settings → Tools & MCP shows the loaded servers and lets you switch individual tools off.

VS Code

Use the button above, or add the entry to .vscode/mcp.json. Because that file lives in the repo, define the key as an input instead of writing it inline. VS Code prompts once and stores the value encrypted:

{
	"inputs": [
		{
			"type": "promptString",
			"id": "serplens-key",
			"description": "SERP Lens API key",
			"password": true
		}
	],
	"servers": {
		"serplens": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@serplens/mcp"],
			"env": {
				"SERPLENS_API_KEY": "${input:serplens-key}"
			}
		}
	}
}

Other clients

Any MCP client that launches a stdio server works. Point it at the command npx with arguments -y @serplens/mcp, with SERPLENS_API_KEY in its environment.

Verify the connection

Run /mcp in Codex or Claude Code to list connected servers and their tools. Cursor shows status under Settings → Tools & MCP, and VS Code has MCP: List Servers.

With the desktop app open you should see 28 tools. Then try a prompt that has to call one, such as "audit https://example.com and summarize the highest-impact issues" or "show my open SERP Lens tabs".

What runs where

Every tool prefers the desktop app. These 5 also work with it closed:

The other 23 cover live page inspection, browser control, VPN locations, and Search Console. Each returns an error naming the tool and asking you to start the app.

A fallback audit reads static HTML, so rendered-DOM checks, layout and paint metrics, and axe accessibility results are missing. The response marks this with "analysisMode": "static-html".

Troubleshooting

Next steps