# mcpMouse

**Repository Path**: x55/mcpMouse

## Basic Information

- **Project Name**: mcpMouse
- **Description**: AI agent的最后一公里，给AI按上眼镜和手，让AI通过该工具操作鼠标获取屏幕信息吧。原创开源，期待openclaw skills调用
- **Primary Language**: Python
- **License**: LGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-13
- **Last Updated**: 2026-03-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DesktopBridge

<p align="center">
  <img src="assets/logo.png" alt="DesktopBridge Logo" width="200"/>
</p>

<p align="center">
  <strong>给AI看到和操作电脑桌面的能力</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/desktop-bridge/">
    <img src="https://img.shields.io/pypi/v/desktop-bridge.svg" alt="PyPI Version"/>
  </a>
  <a href="https://pypi.org/project/desktop-bridge/">
    <img src="https://img.shields.io/pypi/pyversions/desktop-bridge.svg" alt="Python Versions"/>
  </a>
  <a href="https://github.com/desktop-bridge/desktop-bridge/blob/main/LICENSE">
    <img src="https://img.shields.io/pypi/l/desktop-bridge.svg" alt="License"/>
  </a>
</p>

---

## 概述

DesktopBridge 是一个让AI Agent能够看到和操作电脑桌面的基础设施。它充当AI Agent的"眼睛"和"手"，通过标准化的API暴露屏幕捕获和输入控制能力。

### 核心功能

- 📸 **屏幕捕获** - 高性能实时屏幕截图
- 🖱️ **鼠标控制** - 移动、点击、拖拽、滚动
- ⌨️ **键盘控制** - 文本输入、按键、组合键
- 📺 **窗口管理** - 获取窗口信息、激活窗口、关闭窗口
- 🔒 **安全机制** - 物理鼠标检测、紧急停止

### 支持的模式

1. **MCP模式** - 通过Model Context Protocol与AI Agent集成
2. **WebSocket模式** - 实时双向通信
3. **HTTP模式** - REST API + Web控制界面

## 安装

### 方式一: 从PyPI安装

```bash
pip install desktop-bridge
```

### 方式二: 从源码安装

```bash
git clone https://github.com/desktop-bridge/desktop-bridge.git
cd desktop-bridge
pip install -r requirements.txt
```

## 快速开始

### MCP模式 (推荐)

MCP模式让AI Agent可以直接通过MCP协议控制桌面：

```bash
python main.py --mode mcp
```

### HTTP Web界面

启动带Web控制面板的服务器：

```bash
python main.py --mode dashboard
```

然后打开浏览器访问 http://127.0.0.1:8080

### WebSocket API

启动WebSocket服务器：

```bash
python main.py --mode websocket --port 8081
```

## 使用示例

### Python API

```python
from desktop_bridge import DesktopBridgeMCP

# 创建MCP服务器
mcp = DesktopBridgeMCP()

# 运行服务器
await mcp.run()
```

### MCP工具列表

| 工具 | 描述 |
|------|------|
| `see_desktop` | 获取当前桌面截图 |
| `move_mouse` | 移动鼠标到指定位置 |
| `click` | 点击鼠标按钮 |
| `scroll` | 滚动鼠标滚轮 |
| `drag` | 拖拽操作 |
| `type_text` | 输入文本 |
| `press_key` | 按下单个按键 |
| `hotkey` | 按下组合键 |
| `get_window_list` | 获取窗口列表 |
| `set_foreground_window` | 激活窗口 |

## 架构

```
┌─────────────────────────────────────────────────────────────┐
│                      AI Agent (LLM)                        │
│                                                              │
│   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│   │  Computer   │  │   Vision    │  │   Action    │        │
│   │    Use     │  │  (Screens)  │  │  (Controls) │        │
│   └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
│          │                 │                 │               │
└──────────┼─────────────────┼─────────────────┼───────────────┘
           │                 │                 │
           ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────┐
│                    DesktopBridge Server                     │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   MCP/WS/    │  │   Screen     │  │    Input     │      │
│  │   HTTP API   │  │   Capture    │  │   Control    │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│                                                              │
└─────────────────────────────────────────────────────────────┘
           │                 │                 │
           ▼                 ▼                 ▼
      ┌────────┐        ┌────────┐       ┌────────┐
      │ Network│        │  MSS/  │       │ pynput │
      │ Socket │        │ PIL    │       │ Win32  │
      └────────┘        └────────┘       └────────┘
```

## 配置

编辑 `config.ini` 文件：

```ini
[screen]
capture_fps = 5
quality = 85
scale = 0.5

[mouse]
move_duration = 0.1
click_delay = 0.05

[security]
emergency_key = ctrl+f12
physical_mouse_pause = true
```

## 安全考虑

⚠️ **重要提示**

1. **物理鼠标检测** - 当检测到物理鼠标移动时，AI控制会自动暂停
2. **紧急停止** - 按 `Ctrl+F12` 可立即停止所有AI控制
3. **沙箱限制** - 可配置允许的应用程序白名单
4. **只读模式** - 可禁用输入仅保留视觉功能

## 技术栈

- **Python 3.10+**
- **MSS** - 高性能屏幕捕获
- **PyAutoGUI/pynput** - 输入控制
- **pywinauto** - Windows UI自动化
- **FastAPI/aiohttp** - HTTP服务器
- **websockets** - WebSocket通信
- **MCP** - Model Context Protocol

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 贡献

欢迎提交 Issue 和 Pull Request！

---

<p align="center">
  Made with ❤️ for AI Desktop Control
</p>