使用说明

夹管式MCP包装器

一个MCP（模型上下文协议）服务器，它公开了完整的夹片浏览器API到AI编码代理。考虑到令牌效率，非常适合数据提取、网络抓取和自动化测试工作流程。

🙏 信用： 这个包装是建立在优秀的夹片项目by 路易奥古斯蒂以及Pinchtab团队。Pinchtab是一种轻量级的12MB Go二进制文件，通过HTTP API提供浏览器自动化，并提供可访问的第一快照。

为什么要为AI代理使用Pinchtab？

当AI代理需要浏览网页时，效率很重要。Pinchtab提供 节省5-13x的成本 与传统的浏览器自动化相比。

成本比较（实际数字）

任务	传统浏览器	Pinchtab	节省
提取文章文本	~10000个标记（完整DOM）	约800个代币	便宜12.5倍
查找互动元素	~10500个令牌	约3600个代币	便宜3倍
50页监控任务	~0.30美元	~$0.01	便宜30倍

人工智能工作流程的主要优势

1.数据提取和网页抓取

提取干净、结构化的文本，无需HTML开销
可访问性树提供语义结构（角色、标签、状态）
仅在需要时过滤交互式元素

2.网站变更监控

diff=true 仅返回自上次快照以来更改的元素
跟踪价格变化、内容更新或可用性
监控50多个页面，无上下文溢出

3.异步多标签操作

同时运行20+个标签页（相比之下，Playwright为3-5个）
标签锁定可防止代理之间的冲突
每个选项卡~1MB RAM，而完整浏览器实例为50MB+

4.稳定的自动化

稳定元素引用(e0, e1)在CSS更改中幸存下来
没有脆弱的CSS选择器会在重新设计时中断
适用于阻止传统自动化的网站（隐形模式）

快速开始

单线安装

curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

要求： Docker、Node.js 18+、npm

然后重启你的AI代理（OpenCode、Claude Code等）

测试IT

Open https://example.com and take a screenshot

或使用命令：

/browse https://example.com
/screenshot

用例和示例

1.大规模的网络抓取

问题： 从100个电子商务页面中提取产品价格

传统方法：

加载完整DOM（每页约10000个令牌）
手动解析HTML
成本：1000000个代币（约3.00美元）

夹管法：

// Extract structured text only
pinchtab_read_page({url: "https://store.com/product"})
// Returns clean text with prices, descriptions

成本：80000个代币（约0.24美元）
节省：2.76美元（便宜12.5倍）

2.变更检测与监控

问题： 监控竞争对手的价格或新闻更新

// First visit - establish baseline
snapshot1 = pinchtab_snapshot({url: "https://competitor.com/prices"})

// Later visits - get only changes
diff = pinchtab_snapshot({
  url: "https://competitor.com/prices", 
  diff: true
})
// Returns only modified elements (50-200 tokens vs 10,000)

优点：

跟踪50个站点，无上下文溢出
即时检测变化
数据传输量减少200倍

3.多源研究

问题： 同时从10多个文档网站收集信息

// Open multiple tabs in parallel
tab1 = pinchtab_tab_open({url: "https://docs.api1.com"})
tab2 = pinchtab_tab_open({url: "https://docs.api2.com"})
tab3 = pinchtab_tab_open({url: "https://docs.api3.com"})

// Extract text from all tabs
text1 = pinchtab_read_page({tabId: tab1.tabId})
text2 = pinchtab_read_page({tabId: tab2.tabId})
text3 = pinchtab_read_page({tabId: tab3.tabId})

优点：

20+个并发选项卡
无内存问题（每个标签1MB）
异步操作

4.持久的表单自动化

问题： 自动化在网站更新时中断的登录/结账流程

传统选择器中断：

// Brittle - breaks when CSS changes
await page.click('#login-btn')  // ❌

夹管稳定参考：

// Stable - survives redesigns
pinchtab_action({
  tabId: "...",
  kind: "click",
  ref: "e5"  // ✅ Persistent reference
})

5.可访问性优先测试

内置可访问性树：

元素角色（按钮、链接、标题）
可访问的名称和标签
焦点状态和可见性
兼容屏幕阅读器

// Get only interactive elements
interactives = pinchtab_list_interactives()
// Returns: buttons, links, inputs with labels

可用工具

工具	目的
`pinchtab_tab_open`	在新选项卡中打开URL
`pinchtab_read_page`	提取页面文本（令牌高效）
`pinchtab_list_interactives`	获取可点击元素
`pinchtab_snapshot`	获取可访问性树
`pinchtab_action`	点击、键入、填写表格
`pinchtab_screenshot`	拍摄JPEG截图
`pinchtab_evaluate`	运行JavaScript
`pinchtab_download`	使用浏览器会话下载文件（保留Cookie、身份验证、隐藏）
`pinchtab_upload`	将文件上传到文件输入（本地路径、base64或数据URL）
`pinchtab_tab_lock`	锁定选项卡以进行独占访问

CLI集成

开源代码

添加 ~/.config/opencode/opencode.json:

{
  "\$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pinchtab": {
      "type": "local",
      "command": [
        "/usr/bin/node",
        "~/.pinchtab-mcp-wrapper/dist/index.js"
      ],
      "environment": {
        "PINCHTAB_MODE": "external",
        "PINCHTAB_URL": "http://127.0.0.1:9867",
        "PINCHTAB_TOKEN": "opencode-browser-token-secure",
        "MCP_TRANSPORT": "stdio",
        "LOG_LEVEL": "info"
      },
      "enabled": true
    }
  },
  "agent": {
    "browser": {
      "description": "Browser automation specialist",
      "prompt": "Use pinchtab MCP tools for all web browsing tasks. Prefer text extraction over screenshots for efficiency.",
      "tools": {
        "pinchtab*": true,
        "playwright*": false
      }
    }
  },
  "default_agent": "browser"
}

先决条件： 确保Pinchtab Docker容器正在运行：

docker ps | grep pinchtab  # Check if running
docker start pinchtab       # Start if stopped

克劳德代码

添加 .mcp.json:

{
  "mcpServers": {
    "pinchtab": {
      "command": "bash",
      "args": ["~/.pinchtab-mcp-wrapper/run-mcp.sh"]
    }
  }
}

克劳德代码技能（实验）： 我们还为Claude Code CLI用户提供了一个技能文件。看 CLAUDE_CODE_SKILL.md 有关西班牙语的详细安装和使用说明。您可以将此文件保存到 ~/.claude/commands/pinchtab.md 和使用 /pinchtab 直接在CLI中访问完整参考。

光标

添加到Cursor的MCP设置（设置→ 特性→ MCP):

{
  "mcpServers": {
    "pinchtab": {
      "type": "stdio",
      "command": "bash",
      "args": ["~/.pinchtab-mcp-wrapper/run-mcp.sh"]
    }
  }
}

泽德

添加 ~/.config/zed/settings.json:

{
  "assistant": {
    "version": "2",
    "enabled": true
  },
  "context_servers": {
    "pinchtab": {
      "command": "bash",
      "args": ["~/.pinchtab-mcp-wrapper/run-mcp.sh"]
    }
  }
}

多个AI代理的自动配置

安装程序现在可以自动检测并配置多个AI代理的pinchtab：

开源代码 (~/.config/opencode/opencode.json)
克劳德代码 (~/.mcp.json 或 ./.mcp.json)
光标 (~/.config/Cursor/User/settings.json)
泽德 (~/.config/zed/settings.json)

如果配置文件已经存在，安装程序将：

创建备份(.backup.YYYYMMDD_HHMMSS)
使用Node.js自动合并pinchtab配置
保留所有现有设置

无需手动编辑-只需运行安装程序并重新启动AI代理！

安装选项

安装脚本现在支持自动模式检测和优雅回退：

自动模式（默认）

安装程序会自动检测您的环境并选择最佳模式：

curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

发生了什么：

检查Docker（包括macOS特定路径：Homebrew、OrbStack、Docker Desktop）
如果Docker可用→ 构建Docker镜像并使用 docker 模式
如果Docker不可用→ 自动下载Pinchtab二进制文件并使用 external 模式

Docker模式

推荐给大多数用户。需要安装Docker。

export PINCHTAB_MODE=docker
curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

外部模式（二进制）

对于没有Docker的系统。安装程序会自动下载适用于您架构的Pinchtab二进制文件。

export PINCHTAB_MODE=external
curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

macOS支持

安装程序会在以下位置自动检测Docker：

/opt/homebrew/bin/docker （苹果硅上的自制）
/usr/local/bin/docker （英特尔自制）
/Applications/OrbStack.app/Contents/MacOS/../bin/docker （OrbStack）
/Applications/Docker.app/Contents/Resources/bin/docker （Docker桌面）
~/.docker/bin/docker （Docker桌面替代品）

您还可以手动指定Docker路径：

export DOCKER_PATH=/opt/homebrew/bin/docker
curl -fsSL https://raw.githubusercontent.com/BDuba/pinchtab-mcp-wrapper/main/install.sh | bash

手动安装

# Clone
git clone https://github.com/BDuba/pinchtab-mcp-wrapper.git
cd pinchtab-mcp-wrapper

# Build
npm install && npm run build

# Build Docker image
docker build -f pinchtab.Dockerfile -t pinchtab:local .

# Create wrapper
cat > run-mcp.sh << 'EOF'
#!/bin/bash
export PINCHTAB_MODE=docker
export PINCHTAB_TOKEN=opencode-browser-token-secure
export PINCHTAB_DOCKER_IMAGE=pinchtab:local
exec node "$(dirname "$0")/dist/index.js"
EOF
chmod +x run-mcp.sh

配置

截图文件传递（新）

使用时 delivery: "file"，您现在可以使用相对路径和自动命名：

{
  "tool": "screenshot",
  "params": {
    "delivery": "file"
    // Auto-saved to: ~/Pictures/Screenshots/2026-02-21T12-34-56-tab-123.jpg
  }
}

{
  "tool": "screenshot",
  "params": {
    "delivery": "file",
    "path": "google/homepage.jpg"
    // Saved to: ~/Pictures/Screenshots/google/homepage.jpg
  }
}

{
  "tool": "screenshot",
  "params": {
    "delivery": "file",
    "path": "/absolute/path/to/screenshot.png"
    // Absolute paths still work as before
  }
}

变量	描述	默认值
`SCREENSHOTS_DIR`	截图的基本目录	特定于操作系统（~/Pictures/screenshots）
`SCREENSHOTS_AUTO_CREATE`	自动创建目录	`true`
`SCREENSHOTS_PATTERN`	文件名模式	`{timestamp}-{tabId}.jpg`

环境变量

# Transport (v0.5.0+)
MCP_TRANSPORT=stdio               # stdio | streamable-http | sse
MCP_HTTP_PORT=3000                # HTTP server port
MCP_HTTP_HOST=0.0.0.0             # HTTP server host
MCP_AUTH_TYPE=none                # none | bearer | api-key
MCP_AUTH_TOKEN=secret-token       # Auth token for HTTP mode
MCP_ALLOWED_ORIGINS=*             # CORS origins

# Pinchtab connection
PINCHTAB_MODE=docker              # docker | external
PINCHTAB_TOKEN=secret-token       # Auth token
DEFAULT_SNAPSHOT_FORMAT=compact   # compact | text | json
DEFAULT_MAX_TOKENS=2500           # Token budget
SCREENSHOT_DEFAULT_DELIVERY=base64 # base64 | s3 | file

HTTP模式（v0.5.0+）

Pinchtab MCP Wrapper现在支持远程/云部署的流式HTTP传输。

HTTP模式的用例：

云部署（AWS、GCP、Azure）
远程AI代理访问
无服务器架构
跨多个实例的负载平衡

HTTP快速入门：

# Terminal 1: Start MCP server in HTTP mode
export MCP_TRANSPORT=streamable-http
export MCP_HTTP_PORT=3000
export MCP_AUTH_TYPE=bearer
export MCP_AUTH_TOKEN=your-secret-token
npm start

# Terminal 2: Test the HTTP endpoint
curl http://localhost:3000/health

HTTP模式配置：

变量	描述	默认值
`MCP_TRANSPORT`	运输类型	`stdio`
`MCP_HTTP_PORT`	HTTP服务器端口	`3000`
`MCP_HTTP_HOST`	HTTP服务器主机	`0.0.0.0`
`MCP_HTTP_PATH`	MCP端点路径	`/mcp`
`MCP_AUTH_TYPE`	认证类型：无、承载、api密钥	`none`
`MCP_AUTH_TOKEN`	身份验证令牌（承载/api密钥所需）	-
`MCP_ALLOWED_ORIGINS`	CORS允许的来源（逗号分隔）	`*`
`MCP_ENABLE_SESSIONS`	启用有状态会话	`true`
`MCP_SESSION_TIMEOUT`	会话超时（秒）	`3600`

HTTP模式的安全最佳实践：

始终在生产中使用身份验证(MCP_AUTH_TYPE=bearer)
限制CORS来源(MCP_ALLOWED_ORIGINS=https://yourdomain.com)
使用HTTPS和反向代理（nginx、traefik）
保持身份验证令牌的安全并定期轮换 流式HTTP端点详细信息：

在HTTP模式下运行时，MCP服务器公开：

端点	方法	描述
`http://host:port/mcp`	POST/GET	主MCP流式HTTP端点
`http://host:port/health`	GET	健康检查端点
	`http://host:port/health`	GET
`http://host:port/status`	GET	状态端点（健康别名）

LobeChat集成

对于 LobeChat v2 （以及其他基于HTTP的MCP客户端）：

以HTTP模式启动MCP （监听Docker网络访问的所有接口）：

./run-mcp-http-all.sh
# or
export MCP_TRANSPORT=streamable-http
export MCP_HTTP_HOST=0.0.0.0
export MCP_HTTP_PORT=3001
export MCP_AUTH_TYPE=none
npm start

在LobeChat中配置：
- 首选设置 → 插件 → 主控程序
- 添加新的MCP服务器：
  - 名字: pinchtab
  - 类型: HTTP （或 Streamable HTTP)
  - 统一资源定位符: http://172.21.0.1:3001/mcp （根据您的Docker网络调整IP）
  - 认证类型: None
- 点击 “测试连接”
查找正确的IP地址：
- 检查你的Docker网络： docker network inspect bridge
- 查找容器网络的网关IP
- 常见值：
  - 172.17.0.1 -默认Docker桥
  - 172.21.0.1 -自定义网络
  - host.docker.internal -Docker桌面（Mac/Windows）

注：这 run-mcp-http-all.sh 脚本正在监听 0.0.0.0 允许来自任何Docker容器的连接。 MCP客户端配置示例：

// MCP Client Streamable HTTP configuration
{
  "mcpServers": {
    "pinchtab": {
      "transport": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

HTTP标头：

标题	必填	描述
`Authorization`	如果启用了身份验证	`Bearer <token>` 或api密钥的原始令牌
`Content-Type`	是的	`application/json`
`Mcp-Session-Id`	可选	状态模式的会话ID

身份验证示例：

# Bearer token auth
curl -H "Authorization: Bearer your-secret-token" \
     http://localhost:3000/mcp

# API key auth (header)
curl -H "Authorization: your-api-key" \
     http://localhost:3000/mcp

# API key auth (query param)
curl "http://localhost:3000/mcp?api_key=your-api-key"

从AI代理连接：

大多数MCP客户端本机支持Streamable HTTP。使用以下配置您的AI代理：

{
  "mcp": {
    "pinchtab": {
      "type": "http",
      "url": "http://your-server:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

使用一个Pinchtab实例运行多个AI代理

脚本： 您有多个AI代理（OpenCode、LobeChat、Claude Code、Cursor等），并希望为所有这些代理使用一个Pinchtab Docker容器。

问题： 每个AI代理可能需要不同的MCP传输（CLI代理需要stdio，基于服务器的代理需要HTTP）。

解决方案： 将一个Pinchtab容器与多个MCP服务器一起使用：

┌─────────────────────────────────────────────────────────────┐
│                 Pinchtab Docker Container                   │
│                 (http://127.0.0.1:9867)                      │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│              MCP Wrapper HTTP Server                        │
│              (http://0.0.0.0:3001/mcp)                      │
│   • LobeChat ───────┐  • Other HTTP clients ───┐            │
│   • Remote agents ──┘  • Cloud services ───────┘            │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│              MCP Wrapper stdio Servers                      │
│   • OpenCode ───────┐  • Claude Code ───────┐               │
│   • Cursor ─────────┘  • Zed ───────────────┘               │
└─────────────────────────────────────────────────────────────┘

设置步骤：

启动Pinchtab Docker容器：

docker run -d \
  --name pinchtab \
  -p 127.0.0.1:9867:9867 \
  -e PINCHTAB_TOKEN=opencode-browser-token-secure \
  pinchtab:local

为基于服务器的代理（LobeChat等）启动HTTP MCP服务器：

export PINCHTAB_MODE=external
export PINCHTAB_URL=http://127.0.0.1:9867
export PINCHTAB_TOKEN=opencode-browser-token-secure
export MCP_TRANSPORT=streamable-http
export MCP_HTTP_PORT=3001
export MCP_HTTP_HOST=0.0.0.0
export MCP_AUTH_TYPE=none
export MCP_ENABLE_SESSIONS=true
node dist/index.js

配置CLI代理（OpenCode、Claude Code、Cursor、Zed）以使用stdio：
- OpenCode： ~/.config/opencode/opencode.json （参见 OpenCode部分)
- 克劳德代码： .mcp.json （参见克劳德代码部分)
- 光标：MCP设置（请参见光标部分)
- Zed： ~/.config/zed/settings.json （参见 Zed段)
配置基于服务器的代理（LobeChat）以使用HTTP：
- 网址： http://172.21.0.1:3001/mcp
- 类型： Streamable HTTP
- 认证： None

优点：

单个Pinchtab实例 适用于所有AI代理
无端口冲突 （stdio用于CLI，HTTP用于服务器）
资源效率的 （一个浏览器实例）
浏览器状态一致 所有代理

使HTTP MCP服务器持久化：

sudo tee /etc/systemd/system/pinchtab-mcp.service << 'EOF'
[Unit]
Description=Pinchtab MCP HTTP Server
After=network.target docker.service

[Service]
Type=simple
User=root
WorkingDirectory=/root/.pinchtab-mcp-wrapper
ExecStart=/bin/bash -c 'export PINCHTAB_MODE=external && export PINCHTAB_URL=http://127.0.0.1:9867 && export PINCHTAB_TOKEN=opencode-browser-token-secure && export MCP_TRANSPORT=streamable-http && export MCP_HTTP_PORT=3001 && export MCP_HTTP_HOST=0.0.0.0 && export MCP_AUTH_TYPE=none && export MCP_ENABLE_SESSIONS=true && node dist/index.js'
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable pinchtab-mcp
sudo systemctl start pinchtab-mcp

Pinchtab选项（通过Docker）

PINCHTAB_MODE=docker              # docker | external
PINCHTAB_TOKEN=secret-token       # Auth token
DEFAULT_SNAPSHOT_FORMAT=compact   # compact | text | json
DEFAULT_MAX_TOKENS=2500           # Token budget
SCREENSHOT_DEFAULT_DELIVERY=base64 # base64 | s3 | file

Pinchtab选项（通过Docker）

BRIDGE_STEALTH=full          # Bypass bot detection
BRIDGE_BLOCK_IMAGES=true     # Faster loading
BRIDGE_NO_ANIMATIONS=true    # Consistent snapshots
BRIDGE_TIMEOUT=30            # Action timeout (seconds)

故障排除

问题	解决方案
“连接已关闭”	检查 `docker ps`，验证容器是否正在运行
“MCP错误-32000”	完全重新启动AI代理
健康检查超时	`docker logs pinchtab` 对于错误
401错误	验证PINCHTAB_TOKEN匹配

代币效率指南

降低成本的最佳实践：

使用 /text 用于阅读 -800个代币vs 10000个DOM代币
过滤交互 -3600个代币vs 10500个整页代币
使用 diff=true -仅更改了元素（50-200个令牌）
阻止图像/媒体 -加载速度更快，噪音更小
锁定标签 -防止冲突，避免返工

发展

npm install
npm run build
npm test

发布历史

看更改日志.md 查看详细的版本历史和更改。

最新版本：v0.6.1（2026-03-19）

E2E HTTP测试稳定性 -修复了HTTP模式E2E测试中的间歇性超时问题
包含v0.6.0的所有功能

以前版本（v0.6.0）:

Pinchtab v0.7.8支持 -更新到稳定的Pinchtab版本
修复了MCP流式HTTP传输 -提高了连接稳定性和错误处理能力

先前版本:

v0.5.1-Pinchtab v0.6.3支持，文件上传工具
v0.5.0-可流式HTTP传输，多传输架构
v0.4.0-CI/CD管道、ESLint、综合测试套件
v0.2.0-下载工具，Pinchtab 0.6.1，多代理配置

学分和许可证

此MCP包装器基于夹片路易吉·阿戈斯蒂和撰稿人。

夹片： github/pinchtab
MCP协议：模型上下文协议.io

MIT许可证

使用说明

夹管式MCP包装器

为什么要为AI代理使用Pinchtab？

成本比较（实际数字）

人工智能工作流程的主要优势

快速开始

单线安装

测试IT

用例和示例

1.大规模的网络抓取

2.变更检测与监控

3.多源研究

4.持久的表单自动化

5.可访问性优先测试

可用工具

CLI集成

开源代码

克劳德代码

光标

泽德

多个AI代理的自动配置

安装选项

自动模式（默认）

Docker模式

外部模式（二进制）

macOS支持

手动安装

配置

截图文件传递（新）

环境变量

HTTP模式（v0.5.0+）

LobeChat集成

使用一个Pinchtab实例运行多个AI代理

Pinchtab选项（通过Docker）

Pinchtab选项（通过Docker）

Pinchtab选项（通过Docker）

故障排除

代币效率指南

发展

发布历史

学分和许可证

相关 MCP

网页内容抓取服务器

浏览器自动化MCP服务

浏览器自动化MCP服务器

网页内容抓取服务

Playwright浏览器自动化服务器

iOS模拟器交互服务器