> ## Documentation Index > Fetch the complete documentation index at: https://skyvern.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Install and configure Skyvern's MCP server so Claude Desktop, Claude Code, Cursor, Windsurf, Codex, Hermes, OpenClaw, and other AI tools can run browser automations against Skyvern Cloud or a self-hosted instance over OAuth, API key, or local stdio. 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 agents, 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 | | **Agents** | `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, Codex CLI, Cursor, ChatGPT, and other clients that support MCP OAuth | Claude Desktop, Windsurf, Hermes, OpenClaw, headless/CI flows, or any client where you prefer a static key | Self-hosting Skyvern | | **Install required** | None | None | Python 3.11+ and `pip install "skyvern[server]"` | | **Credential** | Browser sign-in with your Skyvern account | API key from [app.skyvern.com](https://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. ## Option A: Sign in with browser (OAuth) Supported clients today: **Claude Code**, **Codex CLI**, **Cursor**, **ChatGPT** (custom connector), 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. ```bash theme={null} 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. ```bash theme={null} codex mcp add skyvern --url https://api.skyvern.com/mcp/ ``` That single command is the entire flow. Codex prints `Detected OAuth support. Starting OAuth flow…`, opens your browser for Skyvern sign-in, stores the token in `~/.codex/`, and exits with `Successfully logged in.` Verify with: ```bash theme={null} codex mcp get skyvern ``` `http_headers` should be empty (`-`). Skyvern tools are now available in any `codex` session. Requires `codex --version` ≥ 0.125.0. If you previously configured Skyvern with an `x-api-key` header, run `codex mcp remove skyvern` first so Codex does not skip the OAuth handshake. You do not need to run `codex mcp login skyvern` after `add` — the OAuth flow runs inline. Use `codex mcp login skyvern` only to re-authenticate after a token expires or to request custom `--scopes`. If `codex mcp add` fails with `resource is not allowed for this authorization server`, your Codex version derived a trailing-slash `resource` from the URL. Pass the slashless resource explicitly: ```bash theme={null} codex mcp add skyvern --url https://api.skyvern.com/mcp/ --oauth-resource https://api.skyvern.com/mcp ``` Skyvern Cloud accepts both forms, so the flag is only needed on older self-hosted deployments. **One-click install** (Cursor 0.43+): [Install Skyvern in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=Skyvern\&config=eyJ0eXBlIjoic3RyZWFtYWJsZS1odHRwIiwidXJsIjoiaHR0cHM6Ly9hcGkuc2t5dmVybi5jb20vbWNwLyJ9) Click the link above (or copy-paste it into your browser's address bar). Cursor opens and prompts you to authenticate via browser sign-in. No manual JSON editing needed. **Manual fallback** (any Cursor release): Add to `~/.cursor/mcp.json`: ```json theme={null} { "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. **ChatGPT custom connector (Developer Mode)** This is not the ChatGPT App Directory. You can add Skyvern as a custom MCP connector immediately without marketplace approval, provided your ChatGPT plan has the custom connector feature available (Plus, Team, and Enterprise plans). 1. In ChatGPT, open **Settings → Connectors** (the path may vary by plan; look under **Integrations** or **Beta features** if Connectors is not visible). 2. Click **Add connector** and choose the **MCP** type. 3. Enter the Skyvern MCP URL: `https://api.skyvern.com/mcp/` 4. ChatGPT detects OAuth support automatically. Follow the browser sign-in prompt to authenticate with your Skyvern account. 5. Once connected, Skyvern tools appear in the tool panel. You can ask ChatGPT to navigate pages, fill forms, extract data, or run multi-step agents. No API key is required — OAuth handles authentication. If your account does not yet show the Connectors option, check **Settings → Beta features** to enable it. ## Option B: API key Use this path for Claude Desktop, Windsurf, Hermes, OpenClaw, headless/CI flows, and any client that does not yet support the MCP OAuth flow. You can also use it with Claude Code, Codex CLI, or Cursor if you prefer a static key (for example, on a server with no browser available for the OAuth callback). Get your API key from [Settings](https://app.skyvern.com) in the Skyvern dashboard, then pick your client below. ```bash theme={null} 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)** 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 theme={null} { "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](https://www.npmjs.com/package/mcp-remote) to bridge the remote MCP server to stdio and requires Node.js >= 20. Add to `~/.cursor/mcp.json`: ```json theme={null} { "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`: ```json theme={null} { "mcpServers": { "Skyvern": { "type": "streamable-http", "url": "https://api.skyvern.com/mcp/", "headers": { "x-api-key": "YOUR_SKYVERN_API_KEY" } } } } ``` Most Codex users should use the OAuth flow above (`codex mcp add skyvern --url https://api.skyvern.com/mcp/`). Use this manual TOML path only when you cannot complete a browser callback, for example on a headless server or in a CI runner. Add to `~/.codex/config.toml`: ```toml theme={null} [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 theme={null} [mcp_servers.skyvern.env_http_headers] x-api-key = "SKYVERN_API_KEY" ``` Using the Skyvern CLI (recommended, writes to all Hermes profiles automatically): ```bash theme={null} 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`): ```yaml theme={null} mcp_servers: skyvern: url: "https://api.skyvern.com/mcp/" headers: x-api-key: "YOUR_SKYVERN_API_KEY" ``` Verify the connection: ```bash theme={null} hermes mcp test skyvern ``` For local stdio mode (self-hosted), use `skyvern setup hermes --local` instead. Using the Skyvern CLI (recommended): ```bash theme={null} 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): ```json theme={null} { "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: ```bash theme={null} 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: ```bash theme={null} 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, use Docker Compose or a source checkout, then 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: ```bash theme={null} 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 local Python process on your machine that connects to your local Skyvern server. Local mode requires Python 3.11, 3.12, or 3.13. ```bash theme={null} pip install ".[server]" ``` ### Recommended local Claude Code flow Run the setup wizard from a Skyvern source checkout or Docker Compose setup: ```bash theme={null} 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 theme={null} skyvern run server ``` ### Manual local MCP config If you want to configure your client manually instead of using the wizard, use stdio transport: ```json theme={null} { "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: ```json theme={null} { "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`. ```toml theme={null} [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`. From Docker Compose or a source checkout, `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`. | 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//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: ```bash theme={null} 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. 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**. ## QA your frontend changes For the local self-hosted path, use Docker Compose or a Skyvern source checkout, then 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 theme={null} pip install ".[server]" 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. 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](https://app.termly.io/policy-viewer/policy.html?policyUUID=1d7aaa1b-5565-415a-8984-7146d254f738). 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, agent definitions, browser/session artifacts, and credentials you explicitly connect through Skyvern. Skyvern may store agents, 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 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. If the browser opens but the MCP client remains unauthenticated, confirm you can sign in to [app.skyvern.com](https://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 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. 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). 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 theme={null} which python3.11 # Use this path in your MCP config ``` You can also use `pipx` to install in an isolated environment: ```bash theme={null} pipx install skyvern ``` Make sure the Skyvern server is running before using MCP tools: ```bash theme={null} 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. Verify that the `command` path in your MCP config is correct: ```bash theme={null} 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.