# 📸 screenshot-mcp

> 给 AI 装上一双眼睛 — 让 Claude Code 能截图、看图、自动清理的 MCP 服务器

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-18+-green)](https://nodejs.org/)
[![Platform](https://img.shields.io/badge/Platform-Windows-blue)](https://github.com)
[![MCP](https://img.shields.io/badge/MCP-Server-purple)](https://modelcontextprotocol.io)

---

## 这是什么？

**screenshot-mcp** 是一个 [MCP (Model Context Protocol)](https://modelcontextprotocol.io) 服务器，让 AI 助手（如 Claude Code）可以直接在你的 Windows 桌面上：

| 能力 | 说明 |
|------|------|
| 📷 **截图** | 全屏截图、区域截图、活动窗口截图 |
| 👁️ **看图** | 读取图片让 AI 视觉分析 |
| 🗑️ **自动删图** | 按条件清理旧截图，用完即走 |

### 工作原理

```
┌──────────────────────┐         MCP 协议          ┌──────────────────────┐
│                      │◄──────────────────────►│                      │
│   Claude Code        │     tools/list           │   screenshot-mcp     │
│   (MCP 客户端)        │     tools/call           │   (MCP 服务器)       │
│                      │                          │                      │
│  "帮我看看桌面" ──────┼── screenshot ──────────►│  PowerShell .NET     │
│  "这个界面怎么样" ─────┼── screenshot_region ────►│  System.Drawing      │
│  "把截图删掉" ────────┼── cleanup ──────────────►│  fs.unlinkSync       │
└──────────────────────┘                          └──────────────────────┘
                                                           │
                                              ┌────────────┴────────────┐
                                              │   Windows 原生截图 API   │
                                              │   (无需额外工具)          │
                                              └─────────────────────────┘
```

---

## 快速开始

### 前置要求

- **Windows** 10/11（截图依赖 Windows GDI+）
- **Node.js** 18 或更高版本
- **Claude Code**（或其他 MCP 客户端）

### 安装

```bash
# 1. 克隆仓库
git clone https://github.com/你的用户名/screenshot-mcp.git
cd screenshot-mcp

# 2. 安装依赖
npm install
```

### 配置（选一种即可）

#### 方式一：全局配置（推荐，所有项目生效）

编辑 `~/.claude.json`（在 `C:\Users\你的用户名\.claude.json`），在 `mcpServers` 里添加：

```json
"mcpServers": {
  "playwright": {
    "type": "stdio",
    "command": "npx",
    "args": ["@playwright/mcp", "--headless"],
    "env": {}
  },
  "screenshot-mcp": {
    "command": "node",
    "args": ["C:\\你的路径\\screenshot-mcp\\src\\index.js"]
  }
}
```

> **路径说明**：`args` 中的路径要改成你电脑上的实际路径，例如：
> - 项目在桌面：`C:\Users\你的用户名\Desktop\screenshot-mcp\src\index.js`
> - 项目在 D 盘：`D:\projects\screenshot-mcp\src\index.js`

#### 方式二：项目级配置（仅当前项目生效）

在项目目录下创建 `.claude/settings.json`：

```json
{
  "mcpServers": {
    "screenshot-mcp": {
      "command": "node",
      "args": ["C:\\你的路径\\screenshot-mcp\\src\\index.js"]
    }
  }
}
```

#### 方式三：`.mcp.json` 文件（自动发现）

在工作目录下创建 `.mcp.json`，Claude Code 会自动发现并加载：

```json
{
  "mcpServers": {
    "screenshot-mcp": {
      "command": "node",
      "args": ["C:\\你的路径\\screenshot-mcp\\src\\index.js"]
    }
  }
}
```

#### 验证配置是否生效

重启 Claude Code 后，随便说一句：

> *"你能用 screenshot-mcp 吗？"*

如果配置正确，Claude 会回答"可以"并调用截图工具。

### 使用

配置好后，在 Claude Code 中直接说：

> 🗣️ *"帮我截个图看看桌面"*
> 🗣️ *"截取当前活动窗口"*
> 🗣️ *"看看这张图片"*
> 🗣️ *"把刚才的截图删掉"*
> 🗣️ *"清理超过1小时的截图"*

---

## 提供的工具

| 工具 | 说明 | 参数 |
|------|------|------|
| `screenshot` | 全屏截图 | `filename`（可选，自定义文件名） |
| `screenshot_region` | 区域/活动窗口截图 | `filename`（可选），`region`（可选：`"active_window"` 或 `"x,y,width,height"`） |
| `view_image` | 读取图片给 AI 分析 | `path`（必填，图片路径） |
| `list_images` | 列出所有截图 | `limit`（可选，默认 20） |
| `delete_image` | 删除指定图片 | `path`（必填） |
| `cleanup` | 批量清理截图 | `older_than_hours`（可选），`pattern`（可选，文件名前缀） |

---

## 使用示例

### 截图 + AI 分析

```
你：帮我截个图，看看我桌面上有什么
Claude：（调用 screenshot 截图）
       （调用 view_image 看图）
      → 你桌面上有这些文件和文件夹……
```

### 截图指定区域

```
你：截取当前活动窗口
Claude：（调用 screenshot_region region="active_window"）
      → 这是当前窗口的内容……
```

### 看完自动清理

```
你：把刚才的截图删掉
Claude：（调用 delete_image 删除指定文件）
      → 已删除
```

---

## 安全性

| 措施 | 说明 |
|------|------|
| 🛡️ **目录限制** | `delete_image` 和 `cleanup` 只能操作 `screenshots/` 目录下的文件 |
| 📦 **文件大小限制** | 图片最大支持 20MB |
| 🔒 **本地存储** | 截图保存在本地 `screenshots/` 目录，不会外传 |
| 🧹 **自动清理** | 支持按时间批量清理，用完即删 |

---

## 技术栈

| 技术 | 用途 |
|------|------|
| [Node.js](https://nodejs.org/) | 运行环境 |
| [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) | MCP 协议实现 |
| PowerShell .NET (System.Drawing) | Windows 原生截图 |
| JSON-RPC 2.0 | 通信协议 |

**纯 Windows 原生实现，无需任何第三方截图工具。**

---

## 在 GitHub 上使用

如果你把这个项目放在 GitHub 上，别人克隆后会得到一份**不带配置的源码**。他们需要：

1. 运行 `npm install` 安装依赖
2. 在自己的 Claude Code 配置中注册这个 MCP 服务器
3. 把 `args` 中的路径改成自己机器上的实际路径

---

## 开源协议

[MIT](LICENSE) — 随便用，随便改，随便玩。

---

## 相关资源

- [MCP 官方文档](https://modelcontextprotocol.io)
- [MCP SDK (TypeScript)](https://github.com/modelcontextprotocol/typescript-sdk)
- [Claude Code](https://claude.ai/code)

---

> **screenshot-mcp** — 给 AI 装上一双眼睛 👀