OnPisteOnPiste
Back to blog

MCP Browser Automation Quick Start: Complete Setup Guide

Keywords: MCP quick start, browser automation setup, Model Context Protocol tutorial, Cursor setup, VS Code browser automation, beginner guide

Want to control your browser directly from your IDE using natural language? This guide gets you from zero to automating in 5 minutes. No coding required. No complex setup. Just install, configure, and start commanding your browser through your AI assistant.

By the end of this guide, you'll be running commands like "navigate to my localhost and test the login form" directly from Cursor, VS Code, or Claude Desktop.

Table of Contents

Reading Time: ~8 minutes | Difficulty: Beginner | Last Updated: January 16, 2026

What You're Building

By the end of this guide, you'll have:

✅ Onpiste Chrome Extension - The automation engine ✅ MCP Server - Bridge between your IDE and browser ✅ IDE Integration - Control browser from Cursor/VS Code/Claude Desktop ✅ Working Automation - Test commands and see results

What You'll Be Able to Do

"Navigate to google.com and search for 'MCP protocol'"
"Check if localhost:3000 is running"
"Test my login form with test credentials"
"Extract all prices from this product page"
"Take a screenshot of the current page"

All from your IDE, without leaving your code editor.

Learn more about MCP browser automation capabilities.

Prerequisites

Required

  • Chrome or Edge browser (version 138 or higher)
  • Node.js version 18 or higher

Choose Your IDE (pick one)

  • Cursor (recommended for beginners)
  • VS Code with GitHub Copilot
  • Claude Desktop
  • Windsurf
  • Zed

Time Required

  • ⏱️ Installation: 3-5 minutes
  • ⏱️ First Test: 1 minute
  • ⏱️ Learning Basics: 5-10 minutes

Installation Steps

Step 1: Install Onpiste Chrome Extension

  1. Open Chrome Web Store

  2. Add to Chrome

    • Click "Add to Chrome"
    • Confirm "Add extension"

  3. Pin Extension (Recommended)

    • Click puzzle icon in Chrome toolbar
    • Find "Onpiste"
    • Click pin icon

  4. Verify Installation

    • Look for Onpiste icon in toolbar
    • Extension should show green/active status

Time: ~1 minute

Onpiste Chrome extension installation

Step 2: Set Up MCP in Your IDE

Choose your IDE and follow the corresponding setup:

Option A: Cursor (Easiest)

Method 1: Automatic Setup

  1. Open Cursor
  2. Press Cmd/Ctrl + Shift + P
  3. Type "Cursor Settings"
  4. Navigate to "MCP" section
  5. Click "Add new global MCP server"
  6. Paste this configuration:
{
  "mcpServers": {
    "onpiste": {
      "command": "npx",
      "args": ["-y", "@onpiste/mcp@latest"]
    }
  }
}
  1. Save and restart Cursor

Method 2: Manual Configuration

  1. Open file: ~/.cursor/mcp.json (Mac/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows)
  2. If file doesn't exist, create it
  3. Paste the configuration above
  4. Save file
  5. Restart Cursor

Verify It Works:

  • Open Cursor chat (Cmd/Ctrl + L)
  • Type: "Navigate to google.com"
  • If MCP is working, Cursor will use the browser automation tool

Time: ~2 minutes

Option B: VS Code

  1. Install GitHub Copilot (if not already installed)

    • Open Extensions (Cmd/Ctrl + Shift + X)
    • Search "GitHub Copilot"
    • Install

  2. Configure MCP

    • Open Settings: Cmd/Ctrl + ,
    • Search "MCP"
    • Find "GitHub Copilot > MCP: Servers"
    • Edit settings.json

  3. Add Configuration

{
  "github.copilot.mcp.servers": {
    "onpiste": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@onpiste/mcp@latest"]
    }
  }
}

  1. Restart VS Code

  2. Verify

    • Open Copilot chat (Cmd/Ctrl + I)
    • Try: "Navigate to google.com using MCP"

Time: ~3 minutes

Option C: Claude Desktop

  1. Locate Config File

    • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Edit Configuration

    • Open file in text editor
    • If file doesn't exist, create it

  3. Add MCP Server

{
  "mcpServers": {
    "onpiste": {
      "command": "npx",
      "args": ["-y", "@onpiste/mcp@latest"]
    }
  }
}

  1. Restart Claude Desktop

  2. Check Connection

    • Look for hammer icon (🔨) in chat
    • Indicates MCP tools are available

Time: ~2 minutes

Option D: Windsurf

  1. Open Windsurf Settings

    • Click gear icon
    • Navigate to "MCP Configuration"

  2. Add Server

{
  "mcpServers": {
    "onpiste": {
      "command": "npx",
      "args": ["-y", "@onpiste/mcp@latest"]
    }
  }
}
  1. Apply Changes
  2. Restart Windsurf

Time: ~2 minutes

Option E: Zed

  1. Open Zed Settings

    • Cmd/Ctrl + ,
    • Navigate to "Context Servers"

  2. Add Configuration

{
  "context_servers": {
    "onpiste": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@onpiste/mcp@latest"]
    }
  }
}
  1. Save and Restart

Time: ~2 minutes

Step 3: Verify Installation

Test Command:

In your IDE's AI chat, try:

Navigate to example.com and tell me the page title

Expected Result:

Your AI assistant should:

  1. Use the MCP browser automation tool
  2. Open Chrome and navigate to example.com
  3. Report back: "The page title is 'Example Domain'"

If It Works: ✅ You're ready to automate!

If It Doesn't Work: See Troubleshooting below

First Automation Commands

Now that everything's set up, try these beginner-friendly commands:

1. Basic Navigation

Navigate to google.com

What Happens:

  • Chrome opens (or switches to existing window)
  • Navigates to google.com
  • AI confirms: "Successfully navigated to google.com"

2. Search Automation

Go to google.com, search for "MCP browser automation", and tell me the top 3 results

What Happens:

  • Navigates to Google
  • Types search query
  • Presses Enter
  • Extracts top 3 results
  • Reports back with titles and URLs

3. Local Development Check

Check if localhost:3000 is running

What Happens:

  • Navigates to localhost:3000
  • Checks if page loads successfully
  • Reports: "Site is running" or "Connection refused"

Perfect for verifying your dev server is up!

4. Screenshot

Take a screenshot of the current page

What Happens:

  • Captures visible area of current tab
  • Returns screenshot
  • Displayed in your IDE chat

Great for quick visual verification.

5. Form Testing

Navigate to localhost:3000/login, fill the form with [email protected] and password123, and submit

What Happens:

  • Goes to your login page
  • Fills email field
  • Fills password field
  • Clicks submit button
  • Reports result

Perfect for quick manual testing replacement.

Explore more use cases and examples.

Common Use Cases

For Web Developers

Deployment Verification:

Check if app.mysite.com is live and loads without errors

API Testing:

Navigate to localhost:3000/api/health and show me the response

UI Verification:

Go to staging.mysite.com/dashboard and verify all widgets are present

For QA/Testing

Smoke Tests:

Test the signup flow:
1. Navigate to /signup
2. Fill form with test data
3. Submit
4. Verify redirect to /dashboard

Cross-Page Validation:

Check these pages load correctly:
- /home
- /about
- /pricing
- /contact

Form Validation:

Test the contact form:
- Submit empty (expect errors)
- Submit with invalid email (expect error)
- Submit valid form (expect success)

For comprehensive testing strategies, see our automated testing guide.

For Research & Data

Competitive Analysis:

Extract pricing information from competitor.com/pricing

Data Collection:

Go to news.ycombinator.com and extract the top 10 post titles

Documentation Lookup:

Navigate to React documentation and find information about useEffect hook

For Daily Productivity

Quick Checks:

Is my GitHub Actions build passing for the latest commit?

Documentation:

Look up Next.js routing documentation and summarize it

Monitoring:

Check if example.com is up and responding

Best Practices

1. Be Specific

Good:

Navigate to localhost:3000, click the "Login" button, fill username with "[email protected]", fill password with "password123", then submit

Less Good:

Test the login

2. Break Complex Tasks into Steps

Good:

First, navigate to the pricing page.
Then extract all plan prices.
Then create a comparison table.

Less Good:

Do pricing analysis on competitor site

3. Verify Results

Always ask for confirmation:

Navigate to my site and confirm the homepage loads correctly

4. Use Natural Language

You don't need to learn commands. Just describe what you want:

Go to Amazon, search for "wireless mouse", and show me the top 5 results with prices

Troubleshooting

Extension Not Connecting

Symptom: AI says "Chrome extension not connected"

Solutions:

  1. Verify extension is installed and enabled

    • Visit chrome://extensions/
    • Find "Onpiste"
    • Ensure toggle is ON

  2. Check Chrome is running

    • Open Chrome browser
    • Extension must be active

  3. Try closing and reopening Chrome

  4. Reinstall extension if needed

MCP Server Not Found

Symptom: AI doesn't recognize browser automation commands

Solutions:

  1. Verify Node.js is installed

    node --version

    Should show v18.0.0 or higher

  2. Test MCP installation manually

    npx @onpiste/mcp@latest

    Should start the server (Ctrl+C to exit)

  3. Check IDE configuration file has correct JSON syntax

  4. Restart IDE after configuration changes

Commands Not Working

Symptom: AI tries but browser doesn't respond

Solutions:

  1. Check Chrome is the active browser
  2. Verify you have active Chrome window/tab
  3. Try command on simple site first (google.com)
  4. Check browser console for errors (F12)

Timeout Errors

Symptom: "Operation timed out"

Solutions:

  1. Increase timeout in command

    Navigate to slow-site.com (wait up to 30 seconds)

  2. Check your internet connection

  3. Try simpler command first

  4. Verify site is actually accessible

Permission Denied

Symptom: "Permission denied" or "Access blocked"

Solutions:

  1. Some enterprise sites block automation
  2. Try on different site to verify setup works
  3. Check if site requires login first
  4. Ensure extension has permissions (chrome://extensions/)

Advanced Configuration

Customize Timeout

Modify your MCP config to change default timeouts:

{
  "mcpServers": {
    "onpiste": {
      "command": "npx",
      "args": ["-y", "@onpiste/mcp@latest"],
      "env": {
        "BROWSER_TIMEOUT": "30000"
      }
    }
  }
}

Use Specific Chrome Profile

{
  "mcpServers": {
    "onpiste": {
      "command": "npx",
      "args": ["-y", "@onpiste/mcp@latest"],
      "env": {
        "CHROME_PROFILE": "Profile 1"
      }
    }
  }
}

Enable Debug Logging

{
  "mcpServers": {
    "onpiste": {
      "command": "npx",
      "args": ["-y", "@onpiste/mcp@latest"],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

Next Steps

Learn More Commands

Now that basics work, explore advanced automation:

Compare with Other Tools

Understand when to use MCP:

Technical Deep Dive

For developers wanting to extend MCP:

Join the Community

Get help and share your automation:

  • Discord - Ask questions, share use cases
  • GitHub - Report issues, contribute
  • Twitter/X - Follow for updates and tips

Frequently Asked Questions

Q: Do I need to know programming to use MCP? A: No! MCP uses natural language. Just describe what you want: "navigate to google.com and search for X". No code required.

Q: Does MCP work with Firefox or Safari? A: Currently, MCP works with Chrome and Edge (Chromium-based browsers). Firefox and Safari support may come in the future.

Q: Can I use MCP for testing production sites? A: Yes! MCP uses your real browser, so you can test any site you have access to, including authenticated pages.

Q: Is MCP automation secure? A: Yes. Everything runs locally on your machine. Your data never leaves your computer. See our privacy-first architecture.

Q: How much does MCP cost? A: The Onpiste extension and MCP server are free. You only pay for AI API usage if you use cloud models. Chrome Built-in AI is completely free.

Q: Can I automate repetitive tasks? A: Absolutely! That's the main use case. Automate deployment checks, form testing, data extraction, monitoring, and more.

Q: What happens if the extension crashes? A: Simply restart Chrome. The MCP server will reconnect automatically when the extension is available again.

Q: Can I run MCP automation in CI/CD? A: Yes, though it requires a display (headless support coming). For CI/CD, consider using the automation programmatically or traditional tools like Playwright for headless needs.

Q: Does MCP support multiple browser tabs? A: Yes! You can open, switch between, and automate across multiple tabs. Try: "Open 3 tabs with these URLs and extract titles from all"

Q: Can I save automation scripts? A: Currently, you repeat commands in your IDE. For reusable workflows, consider creating saved snippets or using the Onpiste extension's built-in recorder (coming soon).

Common Gotchas & Tips

1. Extension Must Be Active

MCP requires the browser extension to be running. If Chrome is closed, commands won't work.

Tip: Keep Chrome open while using MCP automation.

2. Commands Are Conversational

You don't need to learn syntax. Natural language works:

✅ "Go to google.com and search for python tutorials" ❌ browser.navigate("google.com").search("python")

3. AI Interprets Your Intent

The AI figures out how to accomplish your goal:

"Check if my site is working" becomes:

  1. Navigate to site
  2. Verify it loads
  3. Check for errors
  4. Report status

4. Use Follow-up Commands

You can build on previous commands:

> Navigate to github.com
✅ Done

> Search for "MCP servers"
✅ Done (continues from current page)

> Click the first result
✅ Done

5. Logged-in Sessions Work

MCP uses your real browser profile, so you're already logged into sites:

Navigate to my Gmail and check if I have unread messages

Works because you're already logged into Gmail!

Pro Tips

Combine with Other Tools

Read the homepage content, summarize it, then save the summary to summary.txt

MCP handles browser automation, IDE handles file operations.

Use for Quick Checks

Is prod.mysite.com responding?

Faster than opening browser manually.

Test Before Deploying

Check staging.mysite.com - verify homepage loads and no console errors

Catch issues before they reach production.

Document Your Workflows

Save common commands in your project README:

## QA Commands

Check staging:
"Navigate to staging.mysite.com and verify dashboard loads"

Test login:
"Test login form at /login with [email protected]"

Team members can copy-paste to run tests.

Resources

Documentation

Community

Conclusion

Congratulations! You've set up MCP browser automation and ran your first commands. You can now:

✅ Control Chrome from your IDE ✅ Test web applications without leaving your editor ✅ Automate repetitive browser tasks ✅ Extract data from websites ✅ Monitor deployments and services

What's Next?

  1. Practice: Try different commands with sites you use daily
  2. Explore: Read the use cases guide for inspiration
  3. Share: Show your team how MCP improves workflows
  4. Build: Create your own automation patterns

MCP browser automation eliminates context switching and brings web control directly into your development environment. Start simple, experiment, and discover workflows that save you time every day.

Questions? Issues? Join our Discord community or check the troubleshooting guide.

Happy automating! 🚀

Share this article