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 提交到公开仓库或发给不可信方。

架构

方式 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、LOG_LEVEL
config.json	业务配置：应用命令、壁纸目录、重连参数、mcpServers 等

示例 .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，配置方式相同：

字段	值
command	.venv/bin/python 的绝对路径
args	["…/deepin_mcp_server.py"]

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

注意：

1. 须在图形桌面会话用户下由客户端拉起（需要 D-Bus session）。
2. 可与小智并存（各起各的 server 进程）；但不要对同一小智接入点开多个 mcp_pipe。
3. max_result_chars 主要照顾小智侧长度限制；其他客户端一般也能用，返回偏短属正常。

可用工具

工具	作用
open_url	用默认浏览器打开网址/站点别名（如 B站）；已开浏览器时通常新标签
switch_wifi	开关 WiFi
switch_bluetooth	开关蓝牙
get_bluetooth_devices	已连接蓝牙设备
set_brightness	屏幕亮度 0–100
switch_eyes_protection	护眼/自动色温
switch_theme	浅色 / 深色 / 自动主题
switch_wallpaper	随机换壁纸
set_volume	音量 / 静音
set_performance_mode	高性能 / 平衡 / 节能
launch_app	打开/关闭应用（系统 + WPS/钉钉/微信等）
get_system_memory	内存占用
set_font_size	系统字号
file_operation	打开/复制/移动/重命名/删除/建文件夹
read_file_content	读文本文件（有长度限制）
shutdown_system	关机
create_schedule	生成 ICS 日程并通知
music_control	播放/暂停/上一首/下一首（MPRIS）

打开网址

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

• 工具：open_url
• 别名在 config.json → url_aliases（可自行增删）
• 使用系统默认浏览器；已打开时一般会新建标签页

打开第三方应用

launch_app 的 app_name 示例：

app_name	应用
wps	WPS Office
wpsWriter / wpsPresentation / wpsSpreadsheet	文字 / 演示 / 表格
dingtalk	钉钉
wechat	微信
wecom	企业微信

在 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。