Capture Win MCP

捕获赢mcp

MCP（模型上下文协议）服务器，用于捕获macOS窗口和跟踪空间。该服务器为AI助手提供工具，通过yabai和内置的 screencapture 公用事业。

📖 快速入门指南 | 📦 分销指南 | 👨‍💻 开发人员文档

特性

• 列出窗口：获取有关按macOS Space（虚拟桌面）组织的所有窗口的详细信息
• 捕获窗口：按ID截取特定窗口的屏幕截图

先决条件

• macOS（在macOS 15+上测试）
• Python 3.12或更高版本
• 糟糕 窗口管理器

安装yabai

brew install koekeishiya/formulae/yabai
yabai --start-service

安装

方法1：从GitHub安装（推荐）

使用 uv:

uv pip install git+https://github.com/huegli/capture-win-mcp.git

使用 pip:

pip install git+https://github.com/huegli/capture-win-mcp.git

方法2：从PyPI安装

一旦发布到PyPI：

# Using uv
uv pip install capture-win-mcp

# Using pip
pip install capture-win-mcp

方法3：从源代码安装（用于开发）

# Clone the repository
git clone https://github.com/huegli/capture-win-mcp.git
cd capture-win-mcp

# Create virtual environment
uv venv  # or: python3 -m venv venv
source .venv/bin/activate

# Install in editable mode
uv pip install -e .  # or: pip install -e .

用法

作为MCP服务器

Claude桌面配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

如果通过pip/uv安装（推荐）：

{
  "mcpServers": {
    "capture-win": {
      "command": "capture-win-mcp"
    }
  }
}

如果从源目录运行：

{
  "mcpServers": {
    "capture-win": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/capture-win-mcp",
        "run",
        "capture-win-mcp"
      ]
    }
  }
}

如果使用特定的Python环境：

{
  "mcpServers": {
    "capture-win": {
      "command": "/path/to/venv/bin/capture-win-mcp"
    }
  }
}

添加配置后，重新启动Claude Desktop以使更改生效。

可用工具

list_windows

列出按macOS Space组织的所有窗口。

参数：

• format （可选）：输出格式- "json" （默认）或 "summary"

例子：

{
  "format": "summary"
}

退货： 窗口和空间信息包括：

• 空间索引、标签、可见性状态
• 窗口ID、标题、应用程序名称、位置、大小
• 每个空间的窗口数

capture_window

捕获特定窗口的屏幕截图。

参数：

• window_id （必填）：要捕获的窗口ID（从以下位置获取 list_windows)
• include_shadow （可选）：在捕获中包含窗口阴影（默认值： true)

例子：

{
  "window_id": 12345,
  "include_shadow": false
}

退货： 窗口的Base64编码PNG图像

独立使用

您还可以使用原始的窗口跟踪功能：

# Show windows by space
python main.py

# Show spaces summary
python main.py --spaces

# Export to JSON
python main.py --export output.json

发展

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Run the MCP server
python -m capture_win_mcp.server

建筑

• capture_win_mcp/tracker.py：与yabai接口的EnhancedSpaceTracker类
• capture_win_mcp/server.py：使用工具实现MCP服务器
• main.py：用于窗口跟踪的独立CLI工具

故障排除

“未找到yabai”错误

确保yabai已安装并正在运行：

brew install koekeishiya/formulae/yabai
yabai --start-service

窗口捕获失败

• 确保窗口ID有效（使用 list_windows 第一）
• 检查是否授予了macOS屏幕录制权限
• 某些系统窗口可能无法捕获

许可证

麻省理工学院