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 33 tools across 6 categories:

Category	Key tools	What they do
Browser session management	`skyvern_browser_session_create`, `skyvern_browser_session_close`, `skyvern_browser_session_list`, `skyvern_browser_session_connect`	Open, manage, and reuse browser sessions
Browser actions	`skyvern_act`, `skyvern_navigate`, `skyvern_click`, `skyvern_type`, `skyvern_scroll`, `skyvern_select_option`, `skyvern_press_key`, `skyvern_wait`	Control the browser with natural language or CSS/XPath selectors
Data extraction	`skyvern_extract`, `skyvern_screenshot`, `skyvern_evaluate`	Pull structured data from pages, capture screenshots, run JavaScript
Validation	`skyvern_validate`	Check page conditions using AI (returns true/false)
Credentials	`skyvern_credential_list`, `skyvern_credential_get`, `skyvern_credential_delete`	Look up stored credentials for login flows
Workflows	`skyvern_workflow_create`, `skyvern_workflow_run`, `skyvern_workflow_status`, `skyvern_workflow_get`, `skyvern_workflow_update`, `skyvern_workflow_delete`	Build and execute multi-step automations

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.

Which setup should I use?

	Cloud setup (recommended)	Local mode
Best for	Most users — Skyvern Cloud handles everything	Self-hosting Skyvern with your own infrastructure
Install required	None	Python 3.11+ and `pip install skyvern`
How it connects	Your AI client connects to Skyvern Cloud over HTTPS	A local Python process runs on your machine
API key	From app.skyvern.com	From your self-hosted Skyvern instance

If you have a Skyvern Cloud account, use the cloud setup below. It takes 30 seconds and works immediately.

Quick start

Get your API key from Settings in the Skyvern dashboard, then pick your client below.

Claude Code
Claude Desktop
Cursor
Windsurf
Codex

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

Add 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"
      ]
    }
  }
}

This uses mcp-remote to bridge the remote MCP server to stdio. 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"

That’s it — no Python, no pip install, no local server. Your AI assistant connects directly to Skyvern Cloud over HTTPS. Claude Desktop uses mcp-remote to bridge the connection (requires Node.js >= 20).

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

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. 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`

See it in action

Claude Desktop looking up the top Hacker News posts:

Cursor finding programming jobs:

Windsurf searching Form 5500 and downloading files:

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.

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

Running Automations

Multi-Step Automations

Optimization

Going to Production

Debugging

Self-Hosted Deployment

What you can do

Which setup should I use?

Quick start

Switch an existing MCP config

Alternative: Local mode (self-hosted)

Recommended local Claude Code flow

Manual local MCP config

See it in action

Troubleshooting

Getting Started

Running Automations

Multi-Step Automations

Optimization

Going to Production

Debugging

Self-Hosted Deployment

​What you can do

​Which setup should I use?

​Quick start

​Switch an existing MCP config

​Alternative: Local mode (self-hosted)

​Recommended local Claude Code flow

​Manual local MCP config

​See it in action

​Troubleshooting

What you can do

Which setup should I use?

Quick start

Switch an existing MCP config

Alternative: Local mode (self-hosted)

Recommended local Claude Code flow

Manual local MCP config

See it in action

Troubleshooting