T

tampermonkey-mcp

tampermonkey-mcp

本地服务

github.com/Tampermonkey开发工具573 周前更新

关于 tampermonkey-mcp

tampermonkey-mcp 是通过 Tampermonkey Editors 浏览器扩展读写用户脚本的 MCP 服务，面向需要让 AI 助手管理脚本的用户。它提供脚本列表、读取、更新、新建和删除操作。

主要功能

01列出用户脚本及其元数据
02读取指定脚本内容
03更新脚本内容
04创建和删除用户脚本
05通过连接码连接浏览器扩展

适用场景

01检查已安装用户脚本的内容
02修改现有脚本
03创建或移除用户脚本

MCP 相关

该 MCP 服务向 AI 助手提供管理 Tampermonkey 用户脚本的工具。需先获取连接码，并在 Tampermonkey Editors 扩展中输入以建立连接。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y tampermonkey-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmtampermonkey-mcp0.0.4stdio

工具

6

收录的工具列表 · 更新于 2 周前

此工具无需参数。

详细介绍

使用方法

首先安装以下浏览器扩展：

Tampermonkey
适用于 Firefox 或 Chrome 的 Tampermonkey Editors

然后全局安装 tampermonkey-mcp：

npm install -g tampermonkey-mcp@latest

最后，将 AI 助手配置为使用 tampermonkey 工具：

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

助手会调用 tampermonkey_get_connection_code 并返回连接码，你可以在 Tampermonkey Editors 扩展中输入该连接码。

Claude Code 配置示例

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:9222

构建

npm install
npm run all

Tampermonkey MCP 服务架构

概述

本项目实现了一个 MCP（Model Context Protocol）服务，可通过 Tampermonkey Editors 浏览器扩展读取和修改 Tampermonkey 用户脚本。

架构组件

┌─────────────────────────────────────────────────────────────────────────────┐
│                              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       │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘

连接流程

MCP 服务启动 - 在随机可用端口上创建 WebSocket 服务
生成连接码 - 格式：<base32(port - 1024)><auth_token><echo_token>
用户调用 tampermonkey_get_connection_code - 获取连接码
用户在 Tampermonkey Editors 中输入连接码 - 扩展解析连接码以获取端口和认证信息
扩展连接到 MCP 服务 - 通过身份验证完成 WebSocket 握手
MCP 工具可用 - 此时可调用 list、get、patch

身份验证协议

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

MCP 工具

`tampermonkey_get_connection_code`

用途：通过获取 WebSocket 连接码来初始化连接。
必需：必须首先调用，以启动 WebSocket 服务。
输出：要在 Tampermonkey Editors 中输入的连接码。

`tampermonkey_list`

用途：列出所有可用的用户脚本。
输入：可选，按名称模式筛选，或包含 URL 模式。
输出：用户脚本元数据数组（名称、命名空间、路径、requires）。

`tampermonkey_get`

用途：获取特定用户脚本的内容。
输入：path（来自 list），可选的 ifNotModifiedSince 时间戳。
输出：脚本内容、lastModified 时间戳或错误。

`tampermonkey_patch`

用途：更新用户脚本内容。
输入：path、value（新内容），以及可选的 lastModified（用于乐观锁定）。
输出：成功确认或错误。

`tampermonkey_put`

用途：使用给定的名称和命名空间创建新的用户脚本。
输入：value（新脚本），以及可选的 lastModified。
输出：成功确认、创建的脚本路径或错误。
要求：Tampermonkey Editors 1.0.6+ 和 Tampermonkey 5.6+

`tampermonkey_delete`

用途：删除现有用户脚本。
输入：path（来自 list）。
输出：成功确认或错误。
要求：Tampermonkey Editors 1.0.6+ 和 Tampermonkey 5.6+

基本测试

MCP 服务功能

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": {}
    }
  }'

测试 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

评论

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。