npm package: @onpiste/mcp
Description: MCP server for browser automation with advanced task execution capabilities
Author: Onpiste
Latest version: 0.1.11

# @onpiste/mcp

A Model Context Protocol (MCP) server for browser automation that enables AI applications to control and interact with web browsers through a Chrome extension.

## ✨ Features

### Core Capabilities

- 🤖 **AI-Powered Task Execution**: Let AI agents handle complex multi-step browser tasks autonomously
- 🌐 **Advanced Navigation**: Full control over browser navigation including URL navigation, back/forward, and page refresh
- 🖱️ **Smart Interactions**: Click elements, type text, select dropdown options, and press keyboard keys
- 📜 **Flexible Scrolling**: Scroll by pixels, percentage, or directly to specific text on the page
- 🗂️ **Tab Management**: Open, close, switch between tabs, and get information about all open tabs
- 📸 **Visual Capture**: Take screenshots and capture accessibility snapshots of web pages
- 🔍 **State Inspection**: Access page URLs, titles, console logs, and full browser state information
- ⏱️ **Smart Waiting**: Wait for specific time durations or for elements to appear on the page

### Key Advantages

- ⚡ **Fast**: Automation happens locally on your machine, resulting in better performance without network latency
- 🔒 **Private**: Since automation happens locally, your browser activity stays on your device and isn't sent to remote servers
- 👤 **Logged In**: Uses your existing browser profile, keeping you logged into all your services
- 🥷🏼 **Stealth**: Avoids basic bot detection and CAPTCHAs by using your real browser fingerprint
- 🤖 **AI-Ready**: Compatible with AI applications like Cursor, Claude Code, VS Code, Windsurf, Zed, and more

## 🛠️ Installation

### Requirements

- Node.js >= v18.0.0
- Cursor, Claude Code, VS Code, Windsurf, Zed or another MCP Client
- Chrome or Chromium-based browser with the @onpiste extension installed

### Quick Start

1. Install the @onpiste Chrome extension (if not already installed)
2. Configure your AI application using one of the methods below

<details>
<summary><b>Install in Cursor</b></summary>

Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`

Paste the following configuration into your Cursor `~/.cursor/mcp.json` file. You may also install in a specific project by creating `.cursor/mcp.json` in your project folder. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.

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

</details>

<details>
<summary><b>Install in Claude Code</b></summary>

Run this command to add the MCP server. See [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more info.

```sh
claude mcp add onpiste -- npx -y @onpiste/mcp@latest
```

Or manually edit your configuration file:

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

</details>

<details>
<summary><b>Install in VS Code</b></summary>

Add this to your VS Code MCP config file. See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.

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

</details>

<details>
<summary><b>Install in Windsurf</b></summary>

Add this to your Windsurf MCP config file. See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more info.

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

</details>

<details>
<summary><b>Install in Zed</b></summary>

Add this to your Zed `settings.json`. See [Zed Context Server docs](https://zed.dev/docs/assistant/context-servers) for more info.

```json
{
  "context_servers": {
    "onpiste": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@onpiste/mcp@latest"]
    }
  }
}
```

</details>

<details>
<summary><b>Install in Claude Desktop</b></summary>

Open Claude Desktop developer settings and edit your `claude_desktop_config.json` file to add the following configuration. See [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) for more info.

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

</details>

## 🔨 Available Tools

The MCP server provides a comprehensive set of browser automation tools:

### 🤖 AI Task Execution
- `run_task` - Request the agent to complete a task within the browser environment
- `navigate_to` - Navigate to a specified URL with onpiste optimizations

### 🧭 Navigation
- `browser_go_back` - Go back to the previous page
- `browser_go_forward` - Go forward to the next page
- `browser_refresh` - Refresh the current page

### 🖱️ Interaction
- `browser_click` - Perform click on a web page element
- `browser_type` - Type text into an editable element
- `browser_select_option` - Select an option in a dropdown

### ⌨️ Keyboard Operations
- `browser_press_key` - Press a single key on the keyboard
- `browser_send_keys` - Send keys to the page (supports key combinations like Control+A)

### 📜 Scrolling
- `browser_scroll_to_percent` - Scroll to a percentage of the page or element
- `browser_scroll_by` - Scroll by a specified number of pixels
- `browser_scroll_to_text` - Scroll to specific text on the page

### 🗂️ Tab Management
- `browser_get_tabs` - Get information about all open browser tabs
- `browser_switch_tab` - Switch to a different browser tab
- `browser_open_tab` - Open a new browser tab
- `browser_close_tab` - Close a browser tab

### 🔍 State Inspection
- `browser_snapshot` - Capture accessibility snapshot of the current page
- `browser_get_url` - Get the current page URL
- `browser_get_title` - Get the current page title
- `browser_get_console_logs` - Get the console logs from the browser
- `browser_get_state` - Get the current browser state including page information

### 📸 Screenshots
- `browser_screenshot` - Take a screenshot of the current page

### ⏱️ Wait Operations
- `browser_wait` - Wait for a specified time in seconds
- `browser_wait_for_element` - Wait for an element to appear on the page

## 📝 Usage Examples

Once configured, you can interact with your browser through natural language commands in your AI assistant:

```
Navigate to github.com and search for "MCP servers"
```

```
Take a screenshot of the current page
```

```
Click on the login button and fill in the form
```

The MCP server will automatically handle the browser automation through the @onpiste extension.