screeny

🚀 Screeny MCP Server：优先保障隐私的 macOS 截图工具，为 AI 代理服务

Screeny MCP Server 是一款专为 macOS 系统打造的 MCP 服务器，它将隐私保护置于首位。借助该工具，AI 代理能够对预先批准的应用程序窗口进行截图操作，为开发和调试工作提供安全可靠的可视化上下文信息。

⚠️ 重要提示

使用本工具需要具备 屏幕截图权限 并完成 窗口批准设置，具体说明请参考下文。

🚀 快速开始

使用 Screeny MCP Server 前，请确保你已完成以下操作：

1. 授予屏幕截图权限。
2. 完成窗口批准设置。

✨ 主要特性

🔒 优先保障隐私的设计

与其他截图工具不同，Screeny 在进行截图操作前，需要用户对每个窗口进行 明确授权：

• 窗口批准系统：仅能对预先批准的窗口（在设置过程中完成批准）进行截图。
• 用户可控访问：用户可以自主决定哪些窗口可以被访问。
• 非侵入式截图：在后台进行截图操作，不会改变窗口焦点，也不会干扰用户的工作流程。
• 无外部连接：Screeny 完全在本地设备上运行，截图使用完毕后会立即删除。

丰富的工具集

• listWindows：列出所有已批准的、可用于截图的应用程序窗口。
  • 仅显示用户批准的窗口。
• takeScreenshot：根据窗口 ID 对特定窗口进行截图。
  • 后台截图：无需将窗口置于前台，但无法对最小化的窗口进行截图。
  • 提供真实像素数据：提供高保真度的图像，而非 OCR 或文本提取结果。
  • 可压缩图像：必要时，可将大尺寸图像压缩至 1MB 以内。

资源链接

• screeny://info：提供服务器信息和配置详情。

📦 安装指南

安装依赖

你可以使用 pipx 或 uvx 进行安装：

pipx install mcp-server-screeny

{
  "mcpServers": {
    "screeny": {
      "command": "mcp-server-screeny",
      "args": []
    }
  }
}

{
  "mcpServers": {
    "screeny": {
      "command": "uvx",
      "args": ["mcp-server-screeny"]
    }
  }
}

不同客户端配置

Claude Desktop

1. 打开 Claude 设置 → 开发者 → 编辑配置。
2. 添加上述配置信息。
3. 保存配置后，重启 Claude Desktop。

Cursor

1. 打开 Cursor 设置 → 工具与集成 → MCP 工具。
2. 添加上述配置信息。
3. 保存配置后，重启 Cursor。

📚 详细文档

🔧 设置步骤

1. 授予屏幕截图权限（必需）

重要提示：请在进行窗口批准设置前授予此权限。

⚠️ 重要提示

你需要同时为以下两个应用程序授予屏幕截图权限：

1. 终端应用程序（如 Terminal.app、iTerm2 等）：运行设置时必需（设置完成后可禁用）。
2. MCP 主机应用程序（如 Claude Desktop、Cursor）：进行截图操作时必需。

授予权限的步骤如下：

1. 打开 系统设置 > 隐私与安全 > 屏幕与系统音频录制。
2. 点击 "+" 按钮。
3. 添加终端应用程序和 MCP 主机应用程序。
4. 授予权限后，重启这两个应用程序。

2. 窗口批准设置（必需）

完成 MCP 客户端配置后，你可以批准可进行截图的窗口。

# 交互式批准
mcp-server-screeny --setup

# 自动批准所有当前窗口
mcp-server-screeny --setup --allow-all

# 交互式批准
uvx mcp-server-screeny --setup

# 自动批准所有当前窗口
uvx mcp-server-screeny --setup --allow-all

批准信息将保存至 ~/.screeny/approved_windows.json 文件中。若需要更新批准窗口列表，请重新运行设置命令。

🔒 安全与隐私保障

• 仅能对用户批准的窗口进行截图。
• 所有处理操作均在本地设备上进行。
• 截图为临时文件，使用完毕后将立即删除。

🛠️ 故障排除

权限问题

# 测试窗口检测和权限
mcp-server-screeny --debug

# 若窗口发生变化，重新运行设置
mcp-server-screeny --setup

常见问题及解决方案

• "spawn uvx ENOENT" 错误
  • 解决方案：在 MCP 配置中使用 uvx 的完整路径，而非 "uvx"。
  • 查找路径命令：which uvx。
  • 示例路径："/opt/homebrew/bin/uvx" 或 "/usr/local/bin/uvx"。
• "No approved windows found"
  • 解决方案：先运行 mcp-server-screeny --setup 命令（若使用 uvx，则运行 uvx mcp-server-screeny --setup）。
• "Screen Recording permission required" 或 "No windows found"
  • 解决方案：在系统设置 > 隐私与安全 > 屏幕与系统音频录制中授予屏幕录制权限。
    • 点击 "+" 按钮，手动添加 MCP 主机应用程序（如 Claude Desktop、Cursor 等）。
    • 授予权限后，重启 MCP 主机应用程序。
  • 授予权限后，尝试重新运行设置命令。

🤝 贡献代码

欢迎提交拉取请求！你可以自由贡献新的想法、修复漏洞或进行功能增强。

这是我的第一个 MCP 项目，如果你遇到任何问题，请提交 issue，我会尽力修复！

📋 系统要求

• Python 3.10 及以上版本
• macOS 系统
• 屏幕截图权限

📄 许可证

本项目采用 MIT 许可证。