---
title: MCP Server
subtitle: Connect AI assistants to browser automation via Model Context Protocol
slug: going-to-production/mcp
---

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.

## 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](https://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](https://app.skyvern.com) in the Skyvern dashboard, then pick your client below.

<Tabs>
<Tab title="Claude Code">

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

</Tab>
<Tab title="Claude Desktop">
**macOS / Windows (recommended, no Node.js required)**

1. Download [`skyvern-claude-desktop.mcpb`](https://github.com/Skyvern-AI/skyvern/raw/main/skyvern/cli/mcpb/releases/skyvern-claude-desktop.mcpb).
2. Double-click the downloaded `.mcpb` file.
3. When Claude Desktop opens the Skyvern installer preview, click **Install**.
4. In the **Configure Skyvern** dialog, paste your Skyvern API key.
5. 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`

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

This fallback uses [mcp-remote](https://www.npmjs.com/package/mcp-remote) to bridge the remote MCP server to stdio. It still requires Node.js >= 20.

</Tab>
<Tab title="Cursor">

Add to `~/.cursor/mcp.json`:

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

</Tab>
<Tab title="Windsurf">

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

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

</Tab>
<Tab title="Codex">

Add to `~/.codex/config.toml`:

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

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

</Tab>
</Tabs>

That's it — no Python, no `pip install`, no local server. Your AI assistant connects directly to Skyvern Cloud over HTTPS. Claude Desktop on macOS and Windows can use the one-click Skyvern bundle; Linux and advanced setups can still use [mcp-remote](https://www.npmjs.com/package/mcp-remote) with Node.js >= 20.

<Tip>
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.
</Tip>

## 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:

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

<Tip title="Supported Python Versions" icon="fa-brands fa-python">
Local mode requires Python 3.11, 3.12, or 3.13.
</Tip>

```bash
pip install skyvern
```

### Recommended local Claude Code flow

Run the setup wizard from your project or repo root:

```bash
skyvern quickstart
# or: skyvern init
```

Choose:

1. `local`
2. `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:

```bash
skyvern run server
```

### Manual local MCP config

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

<Tabs>
<Tab title="Claude Code">

```json
{
  "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.

</Tab>
<Tab title="Claude Desktop / Cursor / Windsurf">

Add to your client's config file:

```json
{
  "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`.

</Tab>
<Tab title="Codex">

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

</Tab>
</Tabs>

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

<Accordion title="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` |

</Accordion>

## See it in action

**Claude Desktop** looking up the top Hacker News posts:

<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
  <source src="https://github.com/user-attachments/assets/0c10dd96-c6ff-4b99-ad99-f34a5afd04fe" type="video/mp4" />
</video>

**Cursor** finding programming jobs:

<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
  <source src="https://github.com/user-attachments/assets/084c89c9-6229-4bac-adc9-6ad69b41327d" type="video/mp4" />
</video>

**Windsurf** searching Form 5500 and downloading files:

<video style={{ aspectRatio: '16 / 9', width: '100%' }} controls>
  <source src="https://github.com/user-attachments/assets/70cfe310-24dc-431a-adde-e72691f198a7" type="video/mp4" />
</video>

## 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:

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

<Tip>
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.
</Tip>

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

<Accordion title="Claude Desktop bundle updates">
Private Claude Desktop bundles do not auto-update. Download the latest [`skyvern-claude-desktop.mcpb`](https://github.com/Skyvern-AI/skyvern/raw/main/skyvern/cli/mcpb/releases/skyvern-claude-desktop.mcpb) again, then reinstall it by double-clicking the bundle or using **Settings > Extensions**.
</Accordion>

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

```bash
pip install skyvern
skyvern quickstart
# or: skyvern init
```

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

1. Read your `git diff` and the full source of each changed file
2. Generate targeted test cases (plus regression tests for adjacent behavior)
3. Open a browser against your running dev server
4. Run the tests — navigate, click, fill forms, check the DOM
5. 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.

<Tip>
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 — no test files to maintain.
</Tip>

## Troubleshooting

<Accordion title="Invalid API key or 401 errors">
Double-check that your API key is correct. You can find or regenerate it at [Settings](https://app.skyvern.com). 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.
</Accordion>

<Accordion title="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](https://app.skyvern.com).
</Accordion>

<Accordion title="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:

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

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

```bash
pipx install skyvern
```
</Accordion>

<Accordion title="Connection refused (local mode)">
Make sure the Skyvern server is running before using MCP tools:

```bash
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.
</Accordion>

<Accordion title="MCP client doesn't detect Skyvern">
Verify that the `command` path in your MCP config is correct:

```bash
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.
</Accordion>
