Model Context Protocol (MCP)

Skyvern’s Model Context Protocol (MCP) server enables AI applications to interact with websites, fill forms, and automate browser tasks.

Overview

The Model Context Protocol is an open standard for connecting AI applications to external systems. Skyvern’s MCP implementation allows MCP-enabled applications like Claude Desktop, Cursor, and Windsurf to:

Navigate and interact with websites
Fill out forms automatically
Download files from web portals
Extract information from web pages
Complete multi-step web workflows

Supported Applications

Claude Desktop: Anthropic’s desktop app with MCP support
Cursor: AI-powered code editor
Windsurf: Code editor by Codeium
Any custom MCP-enabled application

Prerequisites

Skyvern MCP requires Python 3.11. Other Python versions are not currently supported.

Python 3.11 environment
An MCP-enabled application (Claude Desktop, Cursor, or Windsurf)
Skyvern API key (for cloud mode) from app.skyvern.com

Installation

Install Skyvern

pip install skyvern

Run setup wizard

The setup wizard guides you through configuration:

skyvern init

During setup, you’ll choose:

Skyvern Cloud: Connect to app.skyvern.com (recommended)
Local Mode: Run Skyvern server locally

The wizard will automatically configure your chosen MCP application.

Launch Skyvern server (Local mode only)

If you selected local mode, start the Skyvern server:

skyvern run server

For cloud mode, skip this step.

Configuration

The skyvern init wizard automatically configures the following applications:

Claude Desktop
Cursor
Windsurf
Custom MCP applications

Manual Configuration

For other MCP-enabled applications, add this configuration:

{
  "mcpServers": {
    "Skyvern": {
      "env": {
        "SKYVERN_BASE_URL": "https://api.skyvern.com",
        "SKYVERN_API_KEY": "YOUR_SKYVERN_API_KEY"
      },
      "command": "PATH_TO_PYTHON",
      "args": [
        "-m",
        "skyvern",
        "run",
        "mcp"
      ]
    }
  }
}

Configuration options:

SKYVERN_BASE_URL:
- Cloud: https://api.skyvern.com
- Local: http://localhost:8000
SKYVERN_API_KEY:
- Cloud: Get from app.skyvern.com/settings
- Local: Find in .env file after running skyvern init
PATH_TO_PYTHON: Full path to your Python 3.11 executable

Usage Examples

Claude Desktop

After setup, you can ask Claude to perform web tasks:

Example prompts:

“Look up the top Hackernews posts today”
“Fill out the contact form at example.com with my details”
“Extract pricing information from competitor-site.com”
“Download the latest report from the portal”

Cursor

Cursor can help automate browser tasks during development:

Example prompts:

“Look up the top programming jobs in San Francisco”
“Test the signup flow on our staging site”
“Extract data from this table and save as CSV”

Windsurf

Windsurf integrates Skyvern for web automation:

Example prompts:

“Do a form 5500 search and download some files”
“Check if our demo form is working correctly”
“Scrape product listings from this page”

Setup for Specific Applications

Claude Desktop

Run skyvern init
Select Claude Desktop from the application list
Choose Cloud or Local mode
Restart Claude Desktop
Verify by asking: “Can you browse the web with Skyvern?”

Cursor

Run skyvern init
Select Cursor from the application list
Choose Cloud or Local mode
Restart Cursor
Open the MCP panel to verify Skyvern is connected

Windsurf

Run skyvern init
Select Windsurf from the application list
Choose Cloud or Local mode
Restart Windsurf
Check MCP servers in settings to verify

Custom MCP Application

Run skyvern init
Select Custom MCP App
The wizard will display the configuration JSON
Copy the configuration to your app’s MCP settings
Restart your application

Cloud vs. Local Mode

Cloud Mode (Recommended)

Setup:

Get API key from app.skyvern.com
Run skyvern init and select Cloud

Pros:

No local server management
Managed infrastructure
Always up-to-date
Scales automatically

Cons:

Requires internet connection
Usage-based pricing
Data processed in cloud

Local Mode

Setup:

Run skyvern init and select Local
Start server with skyvern run server

Pros:

Full control and privacy
No usage limits
Can customize LLM providers
Data stays local

Cons:

Requires local setup and maintenance
Must keep server running
Manual updates needed

MCP Tools Available

When Skyvern MCP is configured, the following tools become available to your AI application:

run_browser_task

Executes a browser automation task. Parameters:

url (required): Starting URL
goal (required): Natural language description of the task
payload (optional): Form data to submit
schema (optional): JSON schema for data extraction

Example:

Run a browser task:
- URL: https://news.ycombinator.com
- Goal: Get the top 3 post titles

get_browser_task_status

Retrieves the status of a previously started task. Parameters:

task_id (required): ID from run_browser_task

Example:

Check status of task tsk_abc123

Tips and Best Practices

Be specific in your requests: The more detail you provide, the better the results. Instead of “check the website,” say “navigate to example.com and extract all product prices.”

Use Cloud mode for convenience: Unless you have specific privacy or customization needs, Cloud mode is easier to set up and maintain.

Restart your app after setup: MCP configurations require application restart
Check Python version: Must be 3.11 (run python --version)
Keep API keys secure: Never commit API keys to version control
Test with simple tasks first: Verify setup with easy tasks before complex ones
Monitor task execution: Use the Skyvern dashboard to watch task progress

Common Issues

MCP server not found

Solution:

Restart your MCP application
Verify configuration file location:
- Claude: ~/Library/Application Support/Claude/claude_desktop_config.json (Mac)
- Cursor: .cursor/mcp_config.json
- Windsurf: Check Windsurf settings
Run skyvern init again to reconfigure

Python version error

Solution:

Skyvern MCP requires Python 3.11
Install Python 3.11: brew install python@3.11 (Mac) or download from python.org
Update PATH_TO_PYTHON in config to point to Python 3.11

Authentication fails

Solution:

Verify API key from app.skyvern.com/settings
Check for extra whitespace in API key
Ensure SKYVERN_BASE_URL is correct:
- Cloud: https://api.skyvern.com
- Local: http://localhost:8000

Local server won’t start

Solution:

Check if port 8000 is already in use
Verify all dependencies installed: pip install skyvern
Check logs for specific error messages
Try running skyvern init again

Tasks fail or timeout

Solution:

Check the task recording in Skyvern dashboard
Simplify the task goal
Verify the target website is accessible
Check your API rate limits (Cloud mode)

Debugging

View MCP Logs

Claude Desktop:

# Mac
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
type %APPDATA%\Claude\logs\mcp*.log

Cursor: Check the MCP panel in Cursor settings

Test Configuration

Test if MCP is working:

python -m skyvern run mcp

This should start the MCP server. If it fails, check error messages.

Verify API Connection

For cloud mode:

curl -H "Authorization: Bearer YOUR_API_KEY" https://api.skyvern.com/api/v1/tasks

For local mode:

curl http://localhost:8000/api/v1/tasks

Advanced Configuration

Custom LLM (Local Mode Only)

In local mode, you can configure custom LLM providers:

After skyvern init, edit .env file
Set LLM provider environment variables
Restart Skyvern server

See LLM Configuration for details.

Proxy Settings

If you’re behind a proxy:

{
  "mcpServers": {
    "Skyvern": {
      "env": {
        "SKYVERN_BASE_URL": "https://api.skyvern.com",
        "SKYVERN_API_KEY": "YOUR_API_KEY",
        "HTTP_PROXY": "http://proxy.example.com:8080",
        "HTTPS_PROXY": "http://proxy.example.com:8080"
      },
      "command": "PATH_TO_PYTHON",
      "args": ["-m", "skyvern", "run", "mcp"]
    }
  }
}

Support

For MCP integration help:

Check the GitHub README
Review MCP specification
Email support@skyvern.com
Join the community Discord

Next Steps

Creating Tasks

Learn how to write effective browser automation tasks

Python SDK

Use Skyvern programmatically with Python

Self-Hosting

Run Skyvern on your own infrastructure

API Reference

Full API documentation

Get Started

Running Tasks

Building Workflows

SDK & API

Credentials & Authentication

Advanced Features

Self-Hosted

Integrations

Debugging & Troubleshooting

​Overview

​Supported Applications

​Prerequisites

​Installation

​Configuration

​Manual Configuration

​Usage Examples

​Claude Desktop

​Cursor

​Windsurf

​Setup for Specific Applications

​Claude Desktop

​Cursor

​Windsurf

​Custom MCP Application

​Cloud vs. Local Mode

​Cloud Mode (Recommended)

​Local Mode

​MCP Tools Available

​run_browser_task

​get_browser_task_status

​Tips and Best Practices

​Common Issues

​MCP server not found

​Python version error

​Authentication fails

​Local server won’t start

​Tasks fail or timeout

​Debugging

​View MCP Logs

​Test Configuration

​Verify API Connection

​Advanced Configuration

​Custom LLM (Local Mode Only)

​Proxy Settings

​Support

​Next Steps

Creating Tasks

Python SDK

Self-Hosting

API Reference

Build docs developers (and LLMs) love

Overview

Supported Applications

Prerequisites

Installation

Configuration

Manual Configuration

Usage Examples

Claude Desktop

Cursor

Windsurf

Setup for Specific Applications

Claude Desktop

Cursor

Windsurf

Custom MCP Application

Cloud vs. Local Mode

Cloud Mode (Recommended)

Local Mode

MCP Tools Available

run_browser_task

get_browser_task_status

Tips and Best Practices

Common Issues

MCP server not found

Python version error

Authentication fails

Local server won’t start

Tasks fail or timeout

Debugging

View MCP Logs

Test Configuration

Verify API Connection

Advanced Configuration

Custom LLM (Local Mode Only)

Proxy Settings

Support

Next Steps