Tampermonkey Mcp

io.github.TampermonkeyPublished by GitHub account Tampermonkeyv0.0.4Updated Oct 24, 2026

MCP server to manage your Tampermonkey scripts

VerifiedSTDIODesktop onlyBrowser AutomationDeveloper Tools

Overview

AI-generated overview

Lets an AI assistant read, create, edit and delete Tampermonkey userscripts through the Tampermonkey Editors browser extension.

What you can do
  • Get a connection code and pair the server with the Tampermonkey Editors extension
  • List userscripts, optionally filtered by name or URL pattern
  • Read a script's content and last-modified timestamp
  • Update script content, with optional optimistic locking
  • Create new userscripts and delete existing ones
When to use it
Useful when you keep browser userscripts in Tampermonkey and want an assistant to inspect, rewrite, add or remove them without copy-pasting code into the editor. It is a desktop-only setup for people already using Tampermonkey in Chrome or Firefox.
Requirements
Runs as a local process via npm (npx tampermonkey-mcp or a global install) on a desktop machine. Requires the Tampermonkey extension plus the Tampermonkey Editors extension for Chrome or Firefox, and a connection code from the assistant entered into the Editors extension. Creating and deleting scripts needs Tampermonkey Editors 1.0.6+ and Tampermonkey 5.6+.
Before you install
The assistant can overwrite, create and permanently delete userscripts, so review changes before confirming. Pairing relies on a connection code that grants access to your script library; treat it as a secret and only enter it in the Editors extension. Scripts run in your browser, so assistant-written code should be inspected before use.

Installation

In SourceWeft

  1. Open Tampermonkey Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

How to use

First install the following browser extensions:

Then install tampermonkey-mcp globally:

bash
npm install -g tampermonkey-mcp@latest

Finally configure your AI assistant to use the tampermonkey tool:

bash
{  "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 @anthropic-ai/claude-code
// either use your local checkoutnpm run watchclaude mcp add --transport http --scope project tampermonkey http://localhost:4001/mcp
// or the npm packagenpm install -g tampermonkey-mcp@latestclaude 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// orchromium --user-data-dir=/tmp/chrome-devtools-mcp-test-profile --remote-debugging-port=9222
npm install -g chrome-devtools-mcp@latest// install Tampermonkey and Tampermonkey Editorsclaude 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

bash
npm installnpm 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

  1. MCP Server starts - Creates WebSocket server on a random available port
  2. Connection code generated - Format: <base32(port - 1024)><auth_token><echo_token>
  3. User calls tampermonkey_get_connection_code - Gets the connection code
  4. User enters code in Tampermonkey Editors - Extension parses code to get port and auth
  5. Extension connects to MCP server - WebSocket handshake with authentication
  6. 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

bash
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

bash
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-mcpecho '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | npx -y tampermonkey-mcpecho '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"tampermonkey_list","arguments":{"pattern":""}}}' | npx -y tampermonkey-mcp

Source: README.md at commit 72a8ae1

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.0.4LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.