mirror of
https://github.com/Skyvern-AI/skyvern.git
synced 2026-04-29 12:10:28 +00:00
283 lines
9.3 KiB
Text
283 lines
9.3 KiB
Text
---
|
|
title: MCP Server
|
|
subtitle: Connect AI assistants to browser automation via Model Context Protocol
|
|
slug: going-to-production/mcp
|
|
---
|
|
{/* This file (docs/) and fern/integrations/mcp.mdx must stay in sync. docs/ is for Mintlify, fern/ is for Fern. Minor formatting differences (Tip vs inline text, CardGroup) are OK since the platforms support different components. */}
|
|
|
|
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](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">
|
|
|
|
Add to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `~/.config/Claude/claude_desktop_config.json` on Linux):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"Skyvern": {
|
|
"type": "streamable-http",
|
|
"url": "https://api.skyvern.com/mcp/",
|
|
"headers": {
|
|
"x-api-key": "YOUR_SKYVERN_API_KEY"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
</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.
|
|
|
|
## 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.
|
|
|
|
```bash
|
|
pip install skyvern
|
|
```
|
|
|
|
Before using MCP, start your local Skyvern server:
|
|
|
|
```bash
|
|
skyvern run server
|
|
```
|
|
|
|
Then configure your AI client to use stdio transport:
|
|
|
|
<Tabs>
|
|
<Tab title="Claude Code">
|
|
|
|
```bash
|
|
# For Skyvern Cloud, use https://api.skyvern.com instead of localhost
|
|
claude mcp add --transport stdio skyvern \
|
|
--env SKYVERN_BASE_URL=http://localhost:8000 \
|
|
--env SKYVERN_API_KEY=YOUR_SKYVERN_API_KEY \
|
|
-- python3 -m skyvern run mcp
|
|
```
|
|
|
|
</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>
|
|
You can also run `skyvern init` to auto-detect installed clients and write configs automatically.
|
|
</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>
|
|
|
|
## 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, update it in your MCP config and 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`. If you have multiple Python versions installed, make sure the `command` in your MCP config 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.
|
|
</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.
|
|
</Accordion>
|
|
|