# RobotGo MCP Server

一个基于 Go 语言的 MCP (Model Context Protocol) 服务器,使用 robotgo 自动化库实现桌面自动化功能。这个服务允许 AI 客户端(如 Claude Desktop)通过 MCP 协议控制鼠标、键盘、屏幕等桌面元素。

## ✨ 特性

- 🖱️ **鼠标控制**: 移动、点击、滚动、拖拽
- ⌨️ **键盘控制**: 输入文本、按键、组合键
- 📸 **屏幕操作**: 截图、获取屏幕尺寸、获取像素颜色
- 📋 **剪贴板**: 读写剪贴板内容
- 🔄 **进程管理**: 列出、查找、终止进程
- 🪟 **窗口管理**: 获取、激活、关闭、最小化、最大化窗口
- 🔌 **双传输模式**: 支持 stdio 和 SSE 传输
- 🔐 **SSE 认证**: Bearer Token 认证支持
- 📊 **结构化日志**: JSON 格式日志输出

## 🚀 快速开始

### 安装

**使用 go install（推荐）:**

```bash
go install github.com/lian-yang/robotgo-mcp/cmd/robotgo-mcp@latest
```

安装后，可执行文件会在 `$GOPATH/bin` 或 `$HOME/go/bin` 目录中。

**从源码构建:**

```bash
# 克隆仓库
git clone https://github.com/lian-yang/robotgo-mcp.git
cd robotgo-mcp

# 编译
make build
```

### 运行

**stdio 模式(推荐用于 Claude Desktop):**

```bash
./robotgo-mcp --transport=stdio
```

**SSE 模式(用于远程访问):**

```bash
./robotgo-mcp --transport=sse --port=8080 --auth-token=your-secret-token
```

### 配置 Claude Desktop

在 Claude Desktop 配置文件中添加:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "robotgo": {
      "command": "/path/to/robotgo-mcp",
      "args": ["--transport=stdio"]
    }
  }
}
```

## 📖 使用示例

### 屏幕截图

```
使用 screen:capture 工具截取整个屏幕
```

### 鼠标操作

```
使用 mouse:move 移动鼠标到坐标 (100, 200)
使用 mouse:click 点击鼠标左键
使用 mouse:scroll 向下滚动 10 个单位
```

### 键盘输入

```
使用 keyboard:type 输入 "Hello, World!"
使用 keyboard:hotkey 执行 Ctrl+C 复制操作
```

### 进程管理

```
使用 process:list 列出所有进程
使用 process:find 查找名称包含 "chrome" 的进程
使用 process:kill 终止 PID 为 1234 的进程
```

## 🛠️ 可用工具

### 屏幕工具 (Screen)
- `screen:capture` - 截取屏幕或指定区域
- `screen:get_size` - 获取屏幕尺寸
- `screen:get_pixel` - 获取指定位置像素颜色

### 鼠标工具 (Mouse)
- `mouse:move` - 移动鼠标
- `mouse:click` - 点击鼠标按钮
- `mouse:scroll` - 滚动鼠标滚轮
- `mouse:drag` - 拖拽鼠标
- `mouse:get_position` - 获取鼠标位置

### 键盘工具 (Keyboard)
- `keyboard:type` - 输入文本
- `keyboard:tap` - 按下并释放单个键
- `keyboard:hotkey` - 执行组合键
- `keyboard:press` - 按下并保持
- `keyboard:release` - 释放按键

### 剪贴板工具 (Clipboard)
- `clipboard:get` - 读取剪贴板
- `clipboard:set` - 写入剪贴板
- `clipboard:clear` - 清空剪贴板

### 进程工具 (Process)
- `process:list` - 列出所有进程
- `process:find` - 查找进程
- `process:kill` - 终止进程

### 窗口工具 (Window)
- `window:get_active` - 获取活动窗口
- `window:set_active` - 设置活动窗口
- `window:close` - 关闭窗口
- `window:minimize` - 最小化窗口
- `window:maximize` - 最大化窗口
- `window:get_title` - 获取窗口标题

完整文档请查看 [docs/tools.md](docs/tools.md)

## ⚙️ 配置

### 命令行参数

| 参数 | 环境变量 | 默认值 | 说明 |
|------|---------|--------|------|
| `--transport` | `ROBOTGO_TRANSPORT` | `stdio` | 传输方式 (stdio/sse) |
| `--port` | `ROBOTGO_PORT` | `8080` | SSE 端口 |
| `--host` | `ROBOTGO_HOST` | `127.0.0.1` | SSE 绑定地址 |
| `--auth-token` | `ROBOTGO_AUTH_TOKEN` | `""` | SSE 认证令牌 |
| `--log-level` | `ROBOTGO_LOG_LEVEL` | `info` | 日志级别 |
| `--debug` | - | `false` | 启用调试模式 |

## 🔧 开发

### 系统要求

- Go 1.21+
- GCC (robotgo 依赖)

### 构建

```bash
go build -o robotgo-mcp ./cmd/robotgo-mcp
```

### 测试

```bash
# 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector ./robotgo-mcp

# 手动测试
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./robotgo-mcp
```

## ⚠️ 权限说明

### macOS

在 macOS 上,需要授予辅助功能权限:

1. 系统偏好设置 → 安全性与隐私 → 隐私
2. 选择"辅助功能"
3. 添加终端或您的应用程序到列表中

### Linux

在 Linux 上,可能需要安装额外的依赖:

```bash
# Ubuntu/Debian
sudo apt-get install libx11-dev libxrandr-dev libxtst-dev

# Fedora
sudo dnf install libX11-devel libXrandr-devel libXtst-devel
```

### Windows

Windows 通常不需要额外配置。

## 📝 许可证

MIT License

## 🤝 贡献

欢迎提交 Issue 和 Pull Request!

## 🙏 致谢

- [robotgo](https://github.com/go-vgo/robotgo) - Go 跨平台桌面自动化库
- [mcp-go](https://github.com/mark3labs/mcp-go) - Go 语言的 MCP SDK