Documentation

PuppetMCP is a programmable browser that runs as a remote HTTP MCP server. It allows you to install Puppeteer scripts, expose them as MCP tools, and let your AI assistant browse the web securely from your device.

This documentation will guide you through the installation, configuration, and usage of PuppetMCP to help you get the most out of this powerful automation tool.

Installation

Download PuppetMCP for your platform:

• Windows: Download from the Microsoft Store
• macOS: Download from the App Store

First Launch

After installation, launch PuppetMCP and you'll be greeted with a simple interface to get started. The application runs a local HTTP server that your AI assistant can connect to.

Programmable Browser

PuppetMCP uses Puppeteer under the hood, giving you access to a full Chrome/Chromium browser that can be controlled programmatically.

MCP Server

The Model Context Protocol (MCP) server allows AI assistants to interact with the browser through a standardized interface.

Community Scripts

Browse and install community-contributed scripts to extend functionality. Scripts can automate tasks like form filling, data extraction, testing, and more.

Secure & Local

Everything runs locally on your device. Your AI assistant sends requests to your local PuppetMCP server, ensuring your browsing activities remain private.

Architecture

PuppetMCP consists of three main components:

1. Browser Engine: A Chromium-based browser controlled by Puppeteer
2. MCP Server: HTTP server that exposes browser capabilities as MCP tools
3. Script Manager: Manages and executes community scripts

Workflow

1. Your AI assistant sends a request to the PuppetMCP server
2. PuppetMCP executes the requested script or action
3. Results are returned to the AI assistant
4. The AI assistant can use this data to continue the conversation or task

Server Settings

Configure the HTTP server settings:

• Port: Default is 3000, can be changed in settings
• Host: Usually localhost for security
• CORS: Configure allowed origins if needed

Browser Options

Customize browser behavior:

• Headless Mode: Run browser with or without GUI
• User Agent: Customize the browser's user agent string
• Window Size: Set default viewport dimensions
• Extensions: Enable or disable browser extensions

Installing Scripts

Browse the community scripts library to find scripts that match your needs. Each script includes:

• Description of functionality
• Required parameters
• Expected output format
• Author and rating information

Creating Scripts

You can create your own scripts using Puppeteer's API. Scripts should export functions that return promises and handle errors gracefully.

Script Structure

export async function myScript(page, params) {
  // Your Puppeteer code here
  await page.goto(params.url);
  const result = await page.evaluate(() => {
    // Extract data from page
    return document.title;
  });
  return result;
}

MCP Endpoints

PuppetMCP exposes the following MCP tools:

• navigate: Navigate to a URL
• click: Click an element on the page
• type: Type text into an input field
• screenshot: Take a screenshot of the page
• execute: Execute a community script

Tool Parameters

Each tool accepts specific parameters. For example:

{
  "tool": "navigate",
  "parameters": {
    "url": "https://example.com"
  }
}

Common Issues

Connection Refused: Make sure PuppetMCP is running and the server is started. Check if the port is not blocked by a firewall.

Script Errors: Check the script console for detailed error messages. Ensure all required parameters are provided.

Browser Not Responding: Try restarting PuppetMCP. If the issue persists, clear browser cache and data.

Getting Help

If you encounter issues:

• Check the documentation for common solutions
• Visit our GitHub repository to report issues
• Join our community Discord for support

Best Practices

• Local Only: Only bind to localhost unless you have specific networking needs
• Script Review: Review community scripts before installation
• Authentication: Enable authentication if exposing to network
• HTTPS: Use HTTPS when connecting from external clients

Privacy

PuppetMCP runs entirely on your local machine. No browsing data is sent to external servers. All automation happens locally, giving you complete control over your data.

Is PuppetMCP free?

Yes, PuppetMCP is free to download and use. Some premium features may require a subscription.

What AI assistants work with PuppetMCP?

Any AI assistant that supports the MCP protocol can work with PuppetMCP, including Claude Desktop, ChatGPT with plugins, and custom implementations.

Can I use PuppetMCP for commercial purposes?

Yes, PuppetMCP can be used for commercial automation tasks. Check the license for specific terms.

How do I update PuppetMCP?

Updates are delivered through your platform's app store. The application will notify you when updates are available.