MCP Server

Maintained

io.github.Tampermonkey/tampermonkey-mcp MCP Server

io.github.Tampermonkey/tampermonkey-mcp

MCP server to read and modify Tampermonkey userscripts via AI assistants.

What is the io.github.Tampermonkey/tampermonkey-mcp MCP server?

The Tampermonkey MCP server is an MCP (Model Context Protocol) server that enables AI assistants like Claude to manage Tampermonkey userscripts through the Tampermonkey Editors browser extension. It provides tools to list, read, create, update, and delete userscripts via a secure WebSocket connection.

This server bridges AI assistants with Tampermonkey, allowing you to automate userscript management. After installing the Tampermonkey and Tampermonkey Editors browser extensions, you can configure your AI assistant to list all your scripts, read their content, modify them, and create new ones—all through natural language commands.

How to install io.github.Tampermonkey/tampermonkey-mcp

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

~/Library/Application Support/Claude/claude_desktop_config.json

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

Tools & capabilities

Tools this server exposes to the agent.

tampermonkey_get_connection_code — Initialize connection by getting the WebSocket connection code to enter in Tampermonkey Editors.
tampermonkey_list — List all available userscripts with optional filtering by name pattern or URL pattern.
tampermonkey_get — Retrieve the content of a specific userscript by path.
tampermonkey_patch — Update an existing userscript's content with optimistic locking support.
tampermonkey_put — Create a new userscript with the given name and namespace (requires Tampermonkey Editors 1.0.6+ and Tampermonkey 5.6+).
tampermonkey_delete — Delete an existing userscript by path (requires Tampermonkey Editors 1.0.6+ and Tampermonkey 5.6+).

Use cases

Automate creation and updates of Tampermonkey userscripts through natural language prompts
List and review all installed userscripts to understand what automation is running
Modify existing userscripts without manually opening the browser editor
Create new userscripts programmatically based on AI-generated code
Manage userscript versions and content through an AI assistant

io.github.Tampermonkey/tampermonkey-mcp MCP server FAQ

What is the Tampermonkey MCP server?

It's an MCP server that connects your AI assistant to Tampermonkey, allowing you to manage userscripts (list, read, create, update, delete) through the Tampermonkey Editors browser extension.

Is it free?

Yes, the server is open-source and free to use. You only need the free Tampermonkey browser extension and its Editors companion.

How do I install it in Claude or Cursor?

Install globally with `npm install -g tampermonkey-mcp@latest`, then configure your AI assistant's MCP settings to run `npx -y tampermonkey-mcp@latest`. The server will provide a connection code to enter in the Tampermonkey Editors extension.

Do I need authentication?

Yes, the server uses a WebSocket authentication handshake with tokens. You enter a connection code (generated by the server) in the Tampermonkey Editors extension to establish a secure connection.

What browser extensions do I need?

You need Tampermonkey (the userscript manager) and Tampermonkey Editors (available for Firefox and Chrome) to use this MCP server.

Can I create and delete userscripts?

Yes, with `tampermonkey_put` to create and `tampermonkey_delete` to remove scripts, but these require Tampermonkey Editors 1.0.6+ and Tampermonkey 5.6+.

README (reference)

Source of truth, from the repository.

How to use

First install the following browser extensions:

Tampermonkey
Tampermonkey Editors for Firefox or Chrome

Then install tampermonkey-mcp globally:

npm install -g tampermonkey-mcp@latest

Finally configure your AI assistant to use the tampermonkey tool:

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

Your assistant will call tampermonkey_get_connection_code and return a connection code that you can enter in the Tampermonkey Editors extension.

Claude Code configuration example

npm install -g claude

// either use your local checkout
npm run watch
claude mcp add --transport http --scope project tampermonkey http://localhost:4001/mcp

// or the npm package
npm install -g tampermonkey-mcp@latest
claude mcp add --transport stdio --scope project tampermonkey -- npx -y tampermonkey-mcp

// more browser control needed?
// Open chrome://inspect/#remote-debugging
// [x] Allow remote debugging for this browser instance
// or
chromium --user-data-dir=/tmp/chrome-devtools-mcp-test-profile --remote-debugging-port=9222

npm install -g chrome-devtools-mcp@latest
// install Tampermonkey and Tampermonkey Editors
claude mcp add --transport stdio --scope project chrome-devtools-mcp -- npx -y chrome-devtools-mcp@latest --slim --no-usage-statistics --auto-connect --browser-url http://127.0.0.1:9222

Build

npm install
npm run all

Tampermonkey MCP Server Architecture

Overview

This project implements an MCP (Model Context Protocol) server that allows AI assistants to read and modify Tampermonkey userscripts via the Tampermonkey Editors browser extension.

Architecture Components

┌─────────────────────────────────────────────────────────────────────────────┐
│                              AI Assistant                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   │ MCP Protocol (stdio transport)
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         tampermonkey_mcp (MCP Server)                       │
│                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  server.ts                    │  Main entry point                     │  │
│  │                               │  - HTTP or stdio transport            │  │
│  │                               │  - MCP middleware                     │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                  │                                          │
│                                  ▼                                          │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  tampermonkey.ts              │  MCP Tool Definitions                 │  │
│  │                               │  - tampermonkey_get_connection_code   │  │
│  │                               │  - tampermonkey_list                  │  │
│  │                               │  - tampermonkey_get                   │  │
│  │                               │  - tampermonkey_patch                 │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                  │                                          │
│                                  ▼                                          │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  tampermonkey-ws-client.ts    │  WebSocket Server                     │  │
│  │                               │  - Connection code generation         │  │
│  │                               │  - Authentication handshake           │  │
│  │                               │  - Message relay to extension         │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
                                   │
                                   │ WebSocket (local, port derived from code)
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                   Tampermonkey Editors Extension                            │
│                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  Service Worker               │  Receives connection code,            │  │
│  │                               │  establishes WebSocket connection     │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                  │                                          │
│                                  │ Chrome Extension Messaging               │
│                                  ▼                                          │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  Content Script               │  Bridges extension ↔ Tampermonkey     │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                  │                                          │
│                                  ▼                                          │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │  Tampermonkey                 │  Userscript storage & execution       │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

Connection Flow

MCP Server starts - Creates WebSocket server on a random available port
Connection code generated - Format: <base32(port - 1024)><auth_token><echo_token>
User calls tampermonkey_get_connection_code - Gets the connection code
User enters code in Tampermonkey Editors - Extension parses code to get port and auth
Extension connects to MCP server - WebSocket handshake with authentication
MCP tools become available - list, get, patch can now be called

Authentication Protocol

Extension                              MCP Server
    │                                      │
    │───── auth (token) ──────────────────>│
    │                                      │
    │<──── auth (echo_token) ──────────────│
    │                                      │
    │───── auth (echo_token) ─────────────>│
    │                                      │
    │<──── authOK ─────────────────────────│
    │                                      │
    │<───── pings (every 15s) ─────────────│  (keep-alive)
    │───── pongs ─────────────────────────>│
    │                                      │
    │<───── commands (list/get/patch) ─────│
    │───── responses ─────────────────────>│

MCP Tools

`tampermonkey_get_connection_code`

Purpose: Initialize connection by getting the WebSocket connection code.
Required: Must be called first to start the WebSocket server.
Output: Connection code to enter in Tampermonkey Editors.

`tampermonkey_list`

Purpose: List all available userscripts.
Input: Optional filter by name pattern or include URL pattern.
Output: Array of userscript metadata (name, namespace, path, requires).

`tampermonkey_get`

Purpose: Get content of a specific userscript.
Input: path (from list), optional ifNotModifiedSince timestamp.
Output: Script content, lastModified timestamp, or error.

`tampermonkey_patch`

Purpose: Update userscript content.
Input: path, value (new content), optional lastModified for optimistic locking.
Output: Success confirmation or error.

`tampermonkey_put`

Purpose: Create a new userscript with the given name and namespace.
Input: value (new script), optional lastModified.
Output: Success confirmation, path of created script, or error.
Requires: Tampermonkey Editors 1.0.6+ and Tampermonkey 5.6+

`tampermonkey_delete`

Purpose: Delete an existing userscript.
Input: path (from list).
Output: Success confirmation or error.
Requires: Tampermonkey Editors 1.0.6+ and Tampermonkey 5.6+

Basic testing

MCP Server capabilities

curl -X POST http://localhost:4001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "clientInfo": {
        "name": "curl-client",
        "version": "1.0.0"
      },
      "capabilities": {}
    }
  }'

test stdio

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test-client","version":"1.0.0"},"capabilities":{}}}' | npx -y tampermonkey-mcp
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | npx -y tampermonkey-mcp
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"tampermonkey_list","arguments":{"pattern":""}}}' | npx -y tampermonkey-mcp

Related MCP servers

Zephex

MCP gateway with 10 tools for code analysis, architecture, package audit & security.

CodeCraft

Active

Checks whether generated Minecraft Bedrock content will actually load. Nine read-only tools.

TypeScript

Apache-2.0

View repository →

io.github.Tanshaydar/quartermaster

Active

Local MCP asset intelligence across Unity, Fab, Megascans, Gumroad & Cosmos.

Python

MIT

View repository →

PropSWOT — Property Management AI

Property management AI: work orders, vendors, appliances, and triage for Claude and ChatGPT.

io.github.TaplioOfficial/taplio-linkedin-mcp

Maintained

Draft, schedule, publish, and analyze your LinkedIn posts from your AI assistant via Taplio.

MIT

View repository →

Partelisto

Active

Guest check-in, SES.HOSPEDAJES status, and booking creation for Spanish vacation rentals. No PII.

MIT

View repository →