tampermonkey-mcp
OfficialProvides tools to read, modify, list, create, and delete Tampermonkey userscripts via the Tampermonkey Editors browser extension.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
How to use
First install the following browser extensions:
Then install tampermonkey-mcp globally:
npm install -g tampermonkey-mcp@latestFinally 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 @anthropic-ai/claude-code
// 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:9222Build
npm install
npm run allTampermonkey 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.
Related MCP server: vscode-mcp-server
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 codeUser 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), optionalifNotModifiedSincetimestamp.Output: Script content, lastModified timestamp, or error.
tampermonkey_patch
Purpose: Update userscript content.
Input:
path,value(new content), optionallastModifiedfor optimistic locking.Output: Success confirmation or error.
tampermonkey_put
Purpose: Create a new userscript with the given name and namespace.
Input:
value(new script), optionallastModified.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-mcpTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for AI.TV creators — delegate account operations to your AI agent over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP Server that enables AI assistants to interact with your local browsers.55MIT
- FlicenseAqualityDmaintenanceA portable MCP server enabling AI assistants to operate VS Code, including file management, extension control, and workspace automation.6-
- AlicenseNot gradedqualityCmaintenanceMCP server for managing and playing a running SillyTavern instance, enabling AI coding assistants to read/write character cards, worldbooks, and chats, and to interact as a player via the full generation pipeline.35MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that enables AI assistants to manage SSH terminal sessions, execute commands, and automate server operations through natural language, with multi-tab support and session persistence.MIT