deepin-desktop-mcp

用 MCP 控制本机 Deepin 桌面：WiFi、蓝牙、亮度、主题、音量、应用开关等。

核心是标准 stdio MCP Server（deepin_mcp_server.py），不绑定某一家 Agent。可选两种接入方式：

1. 小智 AI：经 mcp_pipe.py 桥到官方 WSS 接入点（语音控制）

2. 其他 Agent（Cursor / Claude Desktop 等）：客户端直接以 stdio 拉起本 Server

小智协议与官方示例一致：78/mcp-calculator / 小智 MCP 接入说明。

许可证：MIT

免责声明

本项目为第三方开源工具，与 Deepin、小智 AI 官方无关，按「现状（AS IS）」提供，不作任何明示或暗示担保。

本工具可控制系统设置、开关机、读写/删除本地文件等。错误调用、模型误判或配置（尤其是 MCP_ENDPOINT token）泄露，可能导致数据丢失、隐私风险或系统异常。使用即表示你了解并自行承担全部风险；作者不对任何直接或间接损失负责。

请勿将含 token 的 .env、真实接入点 URL 或本地 config.json 提交到公开仓库或发给不可信方。

Related MCP server: android-mcp

架构

方式 A：小智                          方式 B：其他 MCP 客户端
小智设备 / 大模型                     Cursor / Claude Desktop / …
       │                                      │
       ▼                                      │ stdio 直接启动
xiaozhi.me MCP 接入点 (wss://...)             │
       │  mcp_pipe.py 主动连出                 │
       ▼                                      ▼
              deepin_mcp_server.py  (FastMCP, stdio)
                              │
                              ▼
              Deepin 25（nmcli / gsettings / D-Bus / pactl …）

• deepin_mcp_server.py：标准 MCP（stdio），可被任意兼容客户端调用。

• mcp_pipe.py：仅小智需要；把 stdio 桥到云端 WSS。不要自己再开 WebSocket 服务端。

环境要求

• Deepin 25（已按本机 D-Bus / gsettings 适配；其他版本可能需微调）

• Python 3.10+

• 图形桌面会话（D-Bus session 可用）

安装

cd /path/to/deepin-desktop-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
cp config.example.json config.json

配置

分两个文件：

示例 .env：

MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=你的token
LOG_LEVEL=INFO

MCP_ENDPOINT 优先读 .env；若为空，再读 config.json 的 mcp_endpoint。

常用 config.json 字段：

• app_commands：各应用可执行文件候选列表

• wallpaper_dirs：随机壁纸搜索目录

• max_result_chars：返回给小智的最大字符数（建议 ≤1000）

• mcpServers.deepin：stdio 启动命令（默认用 .venv/bin/python）

获取接入点：登录 xiaozhi.me → 智能体「配置角色」→ 右下角 MCP 接入点。

运行（小智 AI）

需先在 .env 填写 MCP_ENDPOINT。

# 推荐
./run.sh

# 或手动
source .venv/bin/activate
python mcp_pipe.py

./run.sh / 无参数的 mcp_pipe.py 会按 config.json 的 mcpServers 启动。

成功日志类似：

MCP_PIPE - INFO - Connecting to WebSocket server...
MCP_PIPE - INFO - Successfully connected to WebSocket server
MCP_PIPE - INFO - Started server process: ...
Processing request of type ListToolsRequest

然后到小智后台刷新，确认 MCP 已接入即可语音控制电脑。

运行（stdio / 其他 Agent）

不连小智时，不要启动 mcp_pipe.py / ./run.sh。让 MCP 客户端自行用 stdio 启动 deepin_mcp_server.py。

command 请用本仓库虚拟环境里的 Python（绝对路径更稳），工作目录建议为本仓库根目录（以便读到 config.json）。

Cursor

在 ~/.cursor/mcp.json（或项目级 MCP 配置）中加入：

{
  "mcpServers": {
    "deepin-desktop": {
      "command": "/绝对路径/deepin-desktop-mcp/.venv/bin/python",
      "args": ["/绝对路径/deepin-desktop-mcp/deepin_mcp_server.py"]
    }
  }
}

保存后在 Cursor 设置里确认 MCP 已启用；应能看到 open_url、launch_app 等工具。

Claude Desktop

编辑 Claude 的 MCP 配置（常见路径：~/.config/Claude/claude_desktop_config.json），写入同样结构：

{
  "mcpServers": {
    "deepin-desktop": {
      "command": "/绝对路径/deepin-desktop-mcp/.venv/bin/python",
      "args": ["/绝对路径/deepin-desktop-mcp/deepin_mcp_server.py"]
    }
  }
}

重启 Claude Desktop 后生效。

任意 stdio MCP 客户端

只要客户端支持「command + args」启动本地 MCP Server，配置方式相同：

stdio 模式下不需要 MCP_ENDPOINT；业务配置仍读本地 config.json（应用命令、壁纸目录等）。

注意：

1. 须在图形桌面会话用户下由客户端拉起（需要 D-Bus session）。

2. 可与小智并存（各起各的 server 进程）；但不要对同一小智接入点开多个 mcp_pipe。

3. max_result_chars 主要照顾小智侧长度限制；其他客户端一般也能用，返回偏短属正常。

可用工具

打开网址

语音示例：「打开 B 站」「打开百度」「打开 https://github.com」

• 工具：open_url

• 别名在 config.json → url_aliases（可自行增删）

• 使用系统默认浏览器；已打开时一般会新建标签页

打开第三方应用

launch_app 的 app_name 示例：

在 config.json 的 app_desktop_ids / app_commands 里按同样格式添加即可扩展更多应用（改完重启 ./run.sh）。

注意事项

1. 不要用 print：stdio 用于 MCP 传输，调试请用 logger。

2. 返回值宜短：小智侧通常限制约 1024 字节。

3. 工具名与 docstring 要清晰：方便大模型决定何时调用。

4. 接入点连接数有上限：不要多开多个 mcp_pipe 连同一接入点。

5. 部分应用需已安装：未安装时 launch_app 会提示找不到命令。

6. 关机/删文件等高危操作：仅在明确意图时调用。

目录说明

deepin-desktop-mcp/
├── .env / .env.example       # 密钥（MCP_ENDPOINT）
├── config.json               # 本地业务配置（勿提交密钥）
├── config.example.json       # 配置模板
├── config_loader.py          # 配置加载
├── deepin_mcp_server.py      # Deepin MCP Server（stdio）
├── mcp_pipe.py               # stdio ↔ 小智 WSS 桥接
├── run.sh                    # 一键启动
├── requirements.txt
├── LICENSE
├── SECURITY.md
└── README.md

常见问题

打开浏览器/设置返回成功但没窗口
旧版直接跑 sensible-browser / dde-control-center 会假成功。当前版本已改为：

• 浏览器：xdg-open 打开默认浏览器（含 linglong Edge）

• 设置：D-Bus org.deepin.dde.ControlCenter1.ShowHome

• 其它应用：优先 dde-am

修改代码后需重启 ./run.sh。

连不上 WebSocket
检查 .env 里 MCP_ENDPOINT 是否完整、网络能否访问 api.xiaozhi.me。

工具列表有了但执行失败
确认在图形会话用户下运行（需要 D-Bus session）。

只想本地测工具、不连小智 / 给 Cursor 等用
见上文「运行（stdio / 其他 Agent）」：客户端直接 stdio 启动 deepin_mcp_server.py，不要跑 ./run.sh。

致谢

• 78/mcp-calculator：小智 MCP 的 stdio ↔ WebSocket 桥接参考实现（mcp_pipe.py 基于其思路）

• Model Context Protocol 与 Python MCP SDK

License

本项目采用 MIT License。