MCP Server

The Skyvern MCP server lets AI assistants like Claude Desktop, Claude Code, Codex, Cursor, and Windsurf control a browser. Your AI can fill out forms, extract data, download files, and run multi-step workflows, all through natural language.

What you can do

The MCP server exposes 75+ tools across many categories. Here are the key ones:

Category	Key tools	What they do
Browser session management	`skyvern_browser_session_create`, `skyvern_browser_session_close`, `skyvern_browser_session_list`, `skyvern_browser_session_get`, `skyvern_browser_session_connect`	Open, manage, and reuse browser sessions, including connecting to a local browser via CDP
Browser actions	`skyvern_act`, `skyvern_navigate`, `skyvern_click`, `skyvern_type`, `skyvern_hover`, `skyvern_scroll`, `skyvern_select_option`, `skyvern_press_key`, `skyvern_wait`	Control the browser with natural language, CSS/XPath selectors, or both (hybrid mode)
Data extraction	`skyvern_extract`, `skyvern_screenshot`, `skyvern_evaluate`	Pull structured JSON from pages, capture screenshots, run JavaScript
Validation	`skyvern_validate`	Assert page conditions in natural language (returns true/false with reasoning)
Credentials & login	`skyvern_login`, `skyvern_credential_list`, `skyvern_credential_get`, `skyvern_credential_delete`	Log in with stored credentials (supports Skyvern vault, Bitwarden, 1Password, Azure Key Vault) with automatic 2FA/TOTP
Workflows	`skyvern_workflow_create`, `skyvern_workflow_run`, `skyvern_workflow_status`, `skyvern_workflow_get`, `skyvern_workflow_update`, `skyvern_workflow_delete`, `skyvern_workflow_cancel`	Build, run, and manage multi-step automations with 23 block types

Additional tools cover tab management, iframe switching, drag-and-drop, file upload, clipboard access, network/console inspection, HAR recording, web storage, auth state persistence, folder management, and cached script management. Your AI assistant decides which tools to call based on your instructions. For example, asking “go to Hacker News and get the top post title” triggers skyvern_browser_session_create, skyvern_navigate, skyvern_extract, and skyvern_browser_session_close automatically.

Pick your setup

You have three ways to connect a client to Skyvern:

	OAuth (sign in with browser)	API key	Local mode
Best for	Claude Code, Cursor, and other clients that support MCP OAuth	Claude Desktop, Windsurf, Codex, Hermes, OpenClaw, or any client where you prefer a static key	Self-hosting Skyvern
Install required	None	None	Python 3.11+ and `pip install skyvern`
Credential	Browser sign-in with your Skyvern account	API key from app.skyvern.com	API key from your self-hosted instance
Where it runs	Directly against Skyvern Cloud over HTTPS	Directly against Skyvern Cloud over HTTPS	Local Python process talking to your Skyvern server

If your client appears in the OAuth section below, start there. Otherwise use the API-key setup. Supported clients today: Claude Code, Cursor, and other MCP clients that support remote HTTP servers with OAuth. Skyvern Cloud publishes standard MCP OAuth discovery metadata, so supported clients can start browser sign-in without a static CLIENT_ID or CLIENT_SECRET in your config. There is no install step. You do not need pip install skyvern, Node.js, or an API key.

Claude Code
Cursor

claude mcp add --transport http skyvern https://api.skyvern.com/mcp/ --scope user

Then run /mcp in Claude Code and follow the authentication prompt. Claude Code opens your browser for Skyvern sign-in and stores the token for future sessions.No --header, no API key. If you previously configured Skyvern with x-api-key, run claude mcp remove skyvern first so Claude Code does not skip the OAuth handshake.

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "Skyvern": {
      "type": "streamable-http",
      "url": "https://api.skyvern.com/mcp/"
    }
  }
}

Use a current Cursor release. Restart Cursor, open MCP settings, and authenticate the Skyvern server when prompted. If the prompt does not appear, update Cursor and reopen MCP settings. Cursor opens your browser for Skyvern sign-in and stores the token for future sessions.

Option B: API key

Use this path for Claude Desktop, Windsurf, Codex, Hermes, OpenClaw, and any client that does not yet support the MCP OAuth flow. You can also use it with Claude Code and Cursor if you prefer a static key. Get your API key from Settings in the Skyvern dashboard, then pick your client below.

claude mcp add-json skyvern '{"type":"http","url":"https://api.skyvern.com/mcp/","headers":{"x-api-key":"YOUR_SKYVERN_API_KEY"}}' --scope user

macOS / Windows (recommended, no Node.js required)

Download skyvern-claude-desktop.mcpb.
Double-click the downloaded .mcpb file.
When Claude Desktop opens the Skyvern installer preview, click Install.
In the Configure Skyvern dialog, paste your Skyvern API key.
Leave Skyvern MCP URL set to https://api.skyvern.com/mcp/ unless you are connecting to a different deployment, then click Save.

If double-clicking is blocked by your system, you can instead open Claude Desktop > Settings > Extensions > Install Extension and select the downloaded file manually.The bundle defaults to https://api.skyvern.com/mcp/ and removes the separate Node.js requirement.Linux, self-hosted, or advanced fallback (requires Node.js >= 20)Add this manual bridge to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "Skyvern": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.skyvern.com/mcp/",
        "--header",
        "x-api-key:YOUR_SKYVERN_API_KEY"
      ]
    }
  }
}

Use this fallback for Linux or any Claude Desktop setup where the one-click bundle is not available. It uses mcp-remote to bridge the remote MCP server to stdio and requires Node.js >= 20.

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "Skyvern": {
      "type": "streamable-http",
      "url": "https://api.skyvern.com/mcp/",
      "headers": {
        "x-api-key": "YOUR_SKYVERN_API_KEY"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "Skyvern": {
      "type": "streamable-http",
      "url": "https://api.skyvern.com/mcp/",
      "headers": {
        "x-api-key": "YOUR_SKYVERN_API_KEY"
      }
    }
  }
}

Add to ~/.codex/config.toml:

[mcp_servers.skyvern]
url = "https://api.skyvern.com/mcp/"

[mcp_servers.skyvern.http_headers]
x-api-key = "YOUR_SKYVERN_API_KEY"

To load the API key from an environment variable instead, use env_http_headers:

[mcp_servers.skyvern.env_http_headers]
x-api-key = "SKYVERN_API_KEY"

Using the Skyvern CLI (recommended, writes to all Hermes profiles automatically):

pip install skyvern
export SKYVERN_API_KEY="YOUR_SKYVERN_API_KEY"
skyvern setup hermes

Or add manually to ~/.hermes/config.yaml (and any profile configs under ~/.hermes/profiles/*/config.yaml):

mcp_servers:
  skyvern:
    url: "https://api.skyvern.com/mcp/"
    headers:
      x-api-key: "YOUR_SKYVERN_API_KEY"

Verify the connection:

hermes mcp test skyvern

For local stdio mode (self-hosted), use skyvern setup hermes --local instead.

Using the Skyvern CLI (recommended):

pip install skyvern
export SKYVERN_API_KEY="YOUR_SKYVERN_API_KEY"
skyvern setup openclaw

Or add manually to ~/.openclaw/openclaw.json (OpenClaw accepts JSON5, but plain JSON works too):

{
  "mcp": {
    "servers": {
      "skyvern": {
        "url": "https://api.skyvern.com/mcp/",
        "transport": "streamable-http",
        "headers": {
          "x-api-key": "YOUR_SKYVERN_API_KEY"
        }
      }
    }
  }
}

OpenClaw accepts JSON5 syntax in openclaw.json. skyvern setup openclaw can read that format, but when it rewrites the file it normalizes the config back to standard JSON, so comments and JSON5-only formatting are not preserved.

Verify the config:

openclaw mcp list
openclaw mcp show skyvern

For local stdio mode (self-hosted), use skyvern setup openclaw --local instead.

MCPorter auto-discovers Skyvern from your existing MCP client configs (Cursor, Claude Code, Windsurf, etc.). If you’ve already set up Skyvern in any of those clients, MCPorter finds it automatically. No extra configuration needed.To check what MCPorter can discover:

pip install skyvern
skyvern setup mcporter

After setup, restart your MCP client. Skyvern should appear as an MCP server and is ready for browser tasks.

Prefer a CLI? For Skyvern Cloud, pip install skyvern then run skyvern setup. For the local self-hosted path, run skyvern quickstart or skyvern init and choose Claude Code during the MCP step.

Switch an existing MCP config

If you already have a Skyvern MCP entry and just need to switch to another API key or base URL, use the CLI instead of hand-editing JSON or TOML:

pip install skyvern
skyvern mcp switch --dry-run
skyvern mcp switch

The switcher scans supported local config files created by skyvern setup or manual setup, shows which ones already contain a Skyvern entry, lets you choose which apps to update, and writes a backup before changing anything. Today it can update:

Claude Code project .mcp.json
Claude Code global ~/.claude.json
Claude Desktop JSON config
Cursor ~/.cursor/mcp.json
Windsurf ~/.codeium/windsurf/mcp_config.json
Codex ~/.codex/config.toml
Hermes ~/.hermes/config.yaml (global + per-profile configs)
OpenClaw ~/.openclaw/openclaw.json

skyvern mcp switch preserves the existing transport shape. Remote configs keep using https://.../mcp/; local stdio configs keep SKYVERN_BASE_URL and SKYVERN_API_KEY in the launched process environment. After switching, restart your AI client. If a config file exists but does not already contain a Skyvern entry, run skyvern setup or use the manual setup snippets on this page first.

Alternative: Local mode (self-hosted)

Use this if you are self-hosting Skyvern and want the MCP server to talk to your own instance instead of Skyvern Cloud. This runs a lightweight Python process on your machine that connects to your local Skyvern server.

Local mode requires Python 3.11, 3.12, or 3.13.

pip install skyvern

Recommended local Claude Code flow

Run the setup wizard from your project or repo root:

skyvern quickstart
# or: skyvern init

Choose:

local
Claude Code during the MCP setup step

When you do that, Skyvern will:

generate local SKYVERN_BASE_URL and SKYVERN_API_KEY
write .mcp.json in the current project when you run inside a repo or app directory
pin the MCP command to the active Python interpreter with python -m skyvern run mcp
install bundled Claude Code skills into .claude/skills/, including /qa

This path stays fully local. Claude Code talks to your local Skyvern server over stdio, so localhost targets work directly and you do not need Skyvern Cloud, mcp-remote, or browser tunneling. Before using MCP, start your local Skyvern server if skyvern init did not already do it:

skyvern run server

Manual local MCP config

If you want to configure your client manually instead of using the wizard, use stdio transport:

Claude Code
Claude Desktop / Cursor / Windsurf
Codex

{
  "mcpServers": {
    "skyvern": {
      "command": "/usr/bin/python3",
      "args": ["-m", "skyvern", "run", "mcp"],
      "env": {
        "SKYVERN_BASE_URL": "http://localhost:8000",
        "SKYVERN_API_KEY": "YOUR_SKYVERN_API_KEY"
      }
    }
  }
}

Write this to .mcp.json in your project root, or to ~/.claude.json for a user-level config. Replace /usr/bin/python3 with the Python interpreter from the environment where you installed Skyvern.

Add to your client’s config file:

{
  "mcpServers": {
    "Skyvern": {
      "command": "/usr/bin/python3",
      "args": ["-m", "skyvern", "run", "mcp"],
      "env": {
        "SKYVERN_BASE_URL": "http://localhost:8000",
        "SKYVERN_API_KEY": "YOUR_SKYVERN_API_KEY"
      }
    }
  }
}

Replace /usr/bin/python3 with the output of which python3. For Skyvern Cloud, change SKYVERN_BASE_URL to https://api.skyvern.com.

[mcp_servers.skyvern]
command = "/usr/bin/python3"
args = ["-m", "skyvern", "run", "mcp"]

[mcp_servers.skyvern.env]
SKYVERN_BASE_URL = "http://localhost:8000"
SKYVERN_API_KEY = "YOUR_SKYVERN_API_KEY"

Replace /usr/bin/python3 with the output of which python3. For Skyvern Cloud, change SKYVERN_BASE_URL to https://api.skyvern.com.

skyvern init and skyvern quickstart can write the local MCP config for you. In a project directory, choosing Claude Code defaults to project-local .mcp.json and installs .claude/skills/qa.

Config file locations by client

Client	Format	Path
Claude Desktop (macOS)	JSON	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Linux)	JSON	`~/.config/Claude/claude_desktop_config.json`
Claude Code (project)	JSON	`.mcp.json` in project root
Claude Code (global)	JSON	`~/.claude.json`
Codex (global)	TOML	`~/.codex/config.toml`
Codex (project)	TOML	`.codex/config.toml` in trusted project
Cursor	JSON	`~/.cursor/mcp.json`
Windsurf	JSON	`~/.codeium/windsurf/mcp_config.json`
Hermes (global)	YAML	`~/.hermes/config.yaml`
Hermes (per-profile)	YAML	`~/.hermes/profiles/<name>/config.yaml`
OpenClaw	JSON5	`~/.openclaw/openclaw.json`

See it in action

Claude Desktop looking up the top Hacker News posts:

Cursor finding programming jobs:

Windsurf searching Form 5500 and downloading files:

Connect to your local browser

You can point your AI assistant at a browser running on your machine instead of a cloud browser. This lets you automate internal tools on localhost, reuse existing login sessions, and verify local dev changes, all through the same MCP tools. Start a local browser with a tunnel so Skyvern Cloud can reach it:

skyvern browser serve --tunnel --use-local-profile

This launches Chrome with your existing cookies and logins, and creates an ngrok tunnel. Your AI assistant can then connect to it:

“Connect to my local browser and check if the dashboard at localhost:3000 renders correctly”

The --use-local-profile flag clones auth-relevant data from your default Chrome profile (cookies, saved passwords, local storage) so the browser starts pre-authenticated. Your original profile is never modified.

This is especially powerful during development: make a code change, then ask your AI assistant to navigate to localhost:3000 and verify it works. Fix code and validate in the same prompt.

Always use --api-key when exposing your browser via tunnel. Without it, anyone with the ngrok URL has full browser control.

Claude Desktop bundle updates

Private Claude Desktop bundles do not auto-update. Download the latest skyvern-claude-desktop.mcpb again, then reinstall it by double-clicking the bundle or using Settings > Extensions.

QA your frontend changes

For the local self-hosted path, run skyvern quickstart or skyvern init, choose local, then choose Claude Code during the MCP step. That writes local stdio MCP config and installs Claude Code skills, including /qa, which reads your git diff, generates browser tests, and runs them against your dev server.

pip install skyvern
skyvern quickstart
# or: skyvern init

Then make a frontend change and type /qa in Claude Code. It will:

Read your git diff and the full source of each changed file
Generate targeted test cases (plus regression tests for adjacent behavior)
Open a browser against your running dev server
Run the tests (navigate, click, fill forms, check the DOM)
Report pass/fail with screenshots

For localhost testing, start your local Skyvern backend and frontend. You do not need skyvern browser serve --tunnel for this path.

The /qa skill uses skyvern_evaluate for fast DOM assertions (~10ms each) and skyvern_act for natural-language interactions. Tests are generated fresh from each diff, so there are no test files to maintain.

Privacy and data handling

Skyvern MCP follows Skyvern’s Privacy Policy. When you use MCP, Skyvern processes the information needed to run the automations you request. This can include prompts, URLs, page content, screenshots, uploaded or downloaded files, workflow definitions, browser/session artifacts, and credentials you explicitly connect through Skyvern. Skyvern may store workflows, run history, artifacts, credentials, and browser/session state as needed to provide the service and support repeatable automations. Only connect accounts, credentials, and websites that you are authorized to automate.

Troubleshooting

Invalid API key or 401 errors

Double-check that your API key is correct. You can find or regenerate it at Settings. Make sure there are no extra spaces or newlines when pasting the key.If you recently regenerated your API key, run skyvern mcp switch if you installed the CLI, or update the MCP config manually, then restart your AI client.

Browser sign-in does not complete

If the browser opens but the MCP client remains unauthenticated, confirm you can sign in to app.skyvern.com in the same browser, then restart authentication from your MCP client. Browser extensions or strict privacy settings can interrupt the sign-in flow.If you previously connected with x-api-key and are switching to OAuth, remove the stale MCP entry first (claude mcp remove skyvern, or delete the entry in ~/.cursor/mcp.json) and re-add it without the headers field. A static header prevents the client from starting OAuth.If the sign-in page shows an authorization failure, start the flow again from your MCP client instead of reloading the browser page.

OAuth session expires

OAuth sessions use the access-token lifetime described in the OAuth setup section above. When authentication expires, re-run the MCP client’s authentication flow. To stop using Skyvern from a client before then, clear that client’s saved Skyvern authentication or remove the Skyvern MCP server entry.

Tools not responding or timing out

Skyvern browser sessions take a few seconds to start. If a tool call times out, try again. The first call in a new session is slower than subsequent ones.If timeouts persist, check that your Skyvern account is active and has available credits at app.skyvern.com.

Python version errors (local mode only)

The Skyvern MCP server requires Python 3.11, 3.12, or 3.13. Check your version with python3 --version. Skyvern’s generated local config already pins the active interpreter path automatically. If you are editing the config manually, make sure the command points to a supported version:

which python3.11
# Use this path in your MCP config

You can also use pipx to install in an isolated environment:

pipx install skyvern

Connection refused (local mode)

Make sure the Skyvern server is running before using MCP tools:

skyvern run server

Confirm the server is reachable at http://localhost:8000. If you changed the port, update SKYVERN_BASE_URL in your MCP config to match.You do not need Skyvern Cloud or browser tunneling for this path. Claude Code talks to the local MCP process over stdio, and that process talks to your local Skyvern server.

MCP client doesn't detect Skyvern

Verify that the command path in your MCP config is correct:

which python3

Use the full absolute path (e.g., /usr/bin/python3 or /Users/you/.pyenv/shims/python3), not just python3. Restart your MCP client after editing the config file.If you used the wizard, re-run skyvern init or skyvern setup claude-code --local from the same Python environment to regenerate the config with the correct interpreter path.

Getting Started

Core Features

Browser Automation

Workflow Blocks

Handling Authentication

Optimization

Going to Production

Debugging

Self-Hosted Deployment

What you can do

Pick your setup

Option B: API key

Switch an existing MCP config

Alternative: Local mode (self-hosted)

Recommended local Claude Code flow

Manual local MCP config

See it in action

Connect to your local browser

QA your frontend changes

Privacy and data handling

Troubleshooting

Getting Started

Core Features

Browser Automation

Workflow Blocks

Handling Authentication

Optimization

Going to Production

Debugging

Self-Hosted Deployment

​What you can do

​Pick your setup

​Option A: Sign in with browser (OAuth)

​Option B: API key

​Switch an existing MCP config

​Alternative: Local mode (self-hosted)

​Recommended local Claude Code flow

​Manual local MCP config

​See it in action

​Connect to your local browser

​QA your frontend changes

​Privacy and data handling

​Troubleshooting

What you can do

Pick your setup

Option A: Sign in with browser (OAuth)

Option B: API key

Switch an existing MCP config

Alternative: Local mode (self-hosted)

Recommended local Claude Code flow

Manual local MCP config

See it in action

Connect to your local browser

QA your frontend changes

Privacy and data handling

Troubleshooting