Claude Desktop Setup Guide

Claude Desktop Setup Guide

Version: 1.0.13
Reading Time: 5 minutes

Overview

Set up Puppeteer MCP with Claude Desktop to enable AI-powered browser automation. Claude will be able to browse websites, take screenshots, fill forms, and extract data on your behalf.

Prerequisites

• Claude Desktop installed on your computer
• Node.js 18.0.0+ and npm 9.0.0+
• Puppeteer MCP installed (see Installation Guide)

Quick Setup (3 Steps)

Step 1: Install Puppeteer MCP

npm install -g puppeteer-mcp

Verify installation:

puppeteer-mcp --version

Step 2: Configure Claude Desktop

Find your Claude Desktop configuration file:

📁 Configuration File Locations

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/claude/claude_desktop_config.json

If the file doesn’t exist, create it with the directory structure.

Add this configuration:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["puppeteer-mcp"],
      "env": {
        "PUPPETEER_MCP_AUTH_TOKEN": "your-secret-token-here"
      }
    }
  }
}

Step 3: Restart Claude Desktop

1. Completely quit Claude Desktop (not just close the window)
2. Start Claude Desktop again
3. Look for “puppeteer” in the available tools list

Configuration Options

Basic Configuration (Recommended)

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["puppeteer-mcp"]
    }
  }
}

This uses default settings - perfect for getting started.

Advanced Configuration

With Authentication

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["puppeteer-mcp"],
      "env": {
        "PUPPETEER_MCP_AUTH_TOKEN": "generate-a-secure-token-here",
        "NODE_ENV": "production"
      }
    }
  }
}

Generate a secure token:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

With Custom Settings

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["puppeteer-mcp"],
      "env": {
        "PUPPETEER_HEADLESS": "true",
        "MAX_SESSIONS": "5",
        "SESSION_TIMEOUT": "1800000",
        "PORT": "3001",
        "DEBUG": "puppeteer:*"
      }
    }
  }
}

Using Global Installation

If you installed globally:

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp"
    }
  }
}

Using Local Project Path

For development or custom builds:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["/path/to/puppeteer-mcp/dist/bin/puppeteer-mcp.js"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

Verify Setup

Check Tool Availability

1. Open Claude Desktop
2. Start a new conversation
3. Type: “What tools do you have available?”
4. Claude should list “puppeteer” among the available tools

Test Browser Automation

Try these commands in Claude:

"Navigate to example.com and take a screenshot"

"Go to Wikipedia and search for 'artificial intelligence'"

"Visit https://news.ycombinator.com and tell me the top 3 stories"

Usage Examples

Basic Web Browsing

Take a Screenshot

Ask Claude:

“Take a screenshot of https://example.com”

Claude will:

1. Create a browser session
2. Navigate to the website
3. Capture a screenshot
4. Show you the image

Extract Information

Ask Claude:

“Go to https://weather.com and tell me today’s weather”

Claude will:

1. Navigate to the weather site
2. Extract relevant information
3. Summarize the weather for you

Form Automation

Fill Out Forms

Ask Claude:

“Go to the contact form at example.com/contact and fill it out with test data”

Claude can:

• Fill text inputs
• Select dropdowns
• Check/uncheck boxes
• Submit forms

Data Extraction

Web Scraping

Ask Claude:

“Extract all product names and prices from shop.example.com”

Claude will:

• Navigate to the page
• Identify product elements
• Extract structured data
• Present it in a readable format

Advanced Automation

Multi-Step Workflows

Ask Claude:

“Log into my test account at demo.example.com (username: test, password: demo123), navigate to the dashboard, and download the monthly report”

Claude can handle complex, multi-step automations.

Best Practices

1. Security Considerations

• Never share real passwords with Claude
• Use test accounts for automation
• Set up authentication tokens for production use
• Run in headless mode for security

2. Clear Instructions

Good vs Bad Instructions

❌ Bad:

“Check that website”

✅ Good:

“Navigate to https://example.com and take a screenshot of the homepage”

❌ Bad:

“Fill the form”

✅ Good:

“Go to example.com/contact, fill the email field with test@example.com, and submit the form”

3. Handle Timeouts

Some websites load slowly. Be patient or specify:

“Navigate to slow-site.com and wait up to 30 seconds for it to load completely”

4. Session Management

Claude automatically manages browser sessions, but you can be explicit:

“Create a new browser session, navigate to example.com, take a screenshot, then close the session”

Troubleshooting

Common Issues

❌ Claude doesn't see the tool

1. Check configuration file syntax:

   # Validate JSON
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

2. Ensure proper file location:

   • The config file must be in the exact location
   • Directory must exist

3. Restart Claude completely:

   • Quit Claude Desktop (Cmd+Q on Mac)
   • Start it again

4. Check logs (if available):

   • Look for MCP-related errors
   • Verify the command runs manually

❌ "Command not found" error

1. Verify installation:

   which puppeteer-mcp  # Should show path
   npx puppeteer-mcp --version  # Should show version

2. Try alternative commands:

   {
     "command": "node",
     "args": ["/usr/local/lib/node_modules/puppeteer-mcp/dist/bin/puppeteer-mcp.js"]
   }

3. Use npx (recommended):

   {
     "command": "npx",
     "args": ["puppeteer-mcp"]
   }

❌ Browser fails to launch

1. Install Chrome dependencies (Linux):

   sudo apt-get install -y chromium-browser

2. Set Chrome path:

   {
     "env": {
       "PUPPETEER_EXECUTABLE_PATH": "/usr/bin/google-chrome"
     }
   }

3. Use Docker for consistent environment

❌ Authentication errors

1. Generate a secure token:

   openssl rand -hex 32

2. Set in both places:

   • Claude config: PUPPETEER_MCP_AUTH_TOKEN
   • Server expects the same token

3. Test without auth first:

   {
     "env": {
       "NODE_ENV": "development"
     }
   }

Debug Mode

Enable detailed logging:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["puppeteer-mcp"],
      "env": {
        "DEBUG": "puppeteer:*",
        "NODE_ENV": "development"
      }
    }
  }
}

Advanced Features

Custom Browser Options

{
  "env": {
    "PUPPETEER_ARGS": "--no-sandbox --disable-setuid-sandbox",
    "PUPPETEER_HEADLESS": "false",
    "DEFAULT_VIEWPORT_WIDTH": "1920",
    "DEFAULT_VIEWPORT_HEIGHT": "1080"
  }
}

Multiple Instances

Run different configurations:

{
  "mcpServers": {
    "puppeteer-prod": {
      "command": "npx",
      "args": ["puppeteer-mcp"],
      "env": {
        "PORT": "3001",
        "NODE_ENV": "production"
      }
    },
    "puppeteer-dev": {
      "command": "npx",
      "args": ["puppeteer-mcp"],
      "env": {
        "PORT": "3002",
        "NODE_ENV": "development",
        "PUPPETEER_HEADLESS": "false"
      }
    }
  }
}

Security Best Practices

1. Always use authentication tokens in production
2. Never expose real credentials to Claude
3. Run in headless mode for security
4. Limit session timeouts to prevent resource leaks
5. Use read-only operations when possible

Next Steps

✅ Setup complete! Now you can:

1. Explore usage examples - See what’s possible
2. Configure advanced settings - Customize behavior
3. Read the full API docs - Learn all capabilities

Getting Help

• 💬 Ask Claude directly about browser automation
• 📚 Check the MCP Documentation
• 🐛 Report issues on GitHub

---

Pro Tip: Start with simple tasks like screenshots, then gradually try more complex automations. Claude learns from your usage patterns! 🤖