Skip to main content
Glama
jijiutong

Xiaozhi Desktop MCP

by jijiutong
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Xiaozhi Desktop MCP

把小智、MCP Client 和本机 Mac 工作流连接起来的安全桌面工具层。

xiaozhi-desktop-mcp 是一个运行在本机的 MCP Server。它把 Obsidian 记忆、App 控制、Claude Code / Codex 会话、Xcode、浏览器、Finder、剪贴板等桌面能力封装成可控工具，让语音助手或 AI Client 能安全地调用本机能力。

它不是新的小智后端，也不是任意 shell 执行器。这个项目的核心是：用 MCP / HTTP 接口暴露能力，同时用白名单、路径限制、待确认动作、鉴权和可观测日志把桌面自动化收进安全边界。

API · Desktop Control Roadmap · 3.0 Migration · Client Examples · Operations · Security · Xiaozhi Integration

License: MIT · Version: 3.0.0 · Python · FastMCP · FastAPI

What It Does

flowchart LR
    U["Voice / MCP Client / HTTP Client"]
    T["Transport Layer<br/>stdio / Streamable HTTP / HTTP API"]
    R["Intent & Dispatch<br/>desktop_intent / api_v1"]
    S["Safety Boundary<br/>allowlists / path checks / pending actions"]
    W["Mac Workflow<br/>Obsidian / Apps / Codex / Xcode / Browser"]

    U --> T --> R --> S --> W

典型场景：

  • “小智，记一下...” -> 写入 Obsidian vault

  • “打开这个项目的 Claude Code” -> 在允许项目里启动可见会话

  • “让 cc 检查 README” -> 创建或发送受控任务

  • “打开 Xcode 并构建” -> 只操作白名单项目

  • “搜索 Obsidian / 打开浏览器 / 控制音乐 / 读写剪贴板” -> 通过统一桌面意图执行

Related MCP server: macos-mcp-tools

Why This Exists

语音助手和 LLM 真正接入桌面时，难点不是“能不能调用命令”，而是“能不能安全、稳定、可追踪地调用本机能力”。

这个项目把桌面自动化里的风险收束成明确规则：

  • App、项目、Xcode、Obsidian 都有白名单或路径边界

  • 中风险动作先进入 pending action，再由用户确认

  • MCP Client 可以走标准协议，普通程序可以走 HTTP API

  • 每次请求都有 request id，方便从客户端追到工具调用

  • HTTP 暴露到非 localhost 时必须开启 token 鉴权

Transports

入口

命令

默认地址

适合场景

MCP stdio

xiaozhi-desktop-mcp

标准输入输出

Claude Desktop、小智 bridge、本机 MCP client

MCP Streamable HTTP

xiaozhi-desktop-mcp-streamable

http://127.0.0.1:8766/mcp

支持 MCP over HTTP 的客户端

HTTP API v1

xiaozhi-desktop-http

http://127.0.0.1:8765/api/v1

Java / Python / Go / 稳定客户端

HTTP API v2

xiaozhi-desktop-http

http://127.0.0.1:8765/api/v2

schema 校验、策略、审计、工作流

如果你接的是标准 MCP Client，优先使用 stdio 或 Streamable HTTP。

如果你只是从普通程序里调用桌面能力，使用 /api/v1/dispatch。

如果你在做新客户端，可以先读 /api/v2/actions 获取参数 schema 和策略说明，再按需调用 /api/v2/dispatch。

Capabilities

能力

说明

Obsidian

保存记忆、创建/打开/追加笔记、每日笔记、搜索、最近记忆

Claude Code / Codex

打开项目、发送指令、slash 命令、切模型、状态查询、继续、聚焦、停止

Project Alias

从 CC_ALLOWED_PROJECTS 生成安全项目别名

Apps

打开、关闭、聚焦或查询 ALLOWED_APPS 白名单内的 macOS App

Xcode

打开项目、build、test、clean、查看最近错误

Browser / Finder / Clipboard

标签页读取与控制、打开搜索、Finder 定位、剪贴板读写

Desktop Perception

全屏/窗口截图、macOS Vision OCR、MCP 图像内容

Accessibility UI

UI 树、元素状态，以及确认后的点击、输入、滚动、拖拽、菜单和文件选择

Music

Apple Music 状态/音量控制、网易云播放和客户端内搜索

Pending Actions

SQLite 持久化、TTL、原子确认、防重复执行

Workflows

多步骤计划、暂停确认、重启恢复、继续和取消

Audit

SQLite 脱敏审计，只保存参数名，不保存参数值

Diagnostics

健康检查、配置摘要、工具目录、会话清理

Observability

X-Request-Id、请求日志、工具调用耗时、错误追踪

Quick Start

git clone git@github.com:jijiutong/xiaozhi-desktop-mcp.git
cd xiaozhi-desktop-mcp

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

cp .env.example .env

编辑 .env，至少确认这些配置：

OBSIDIAN_VAULT=/path/to/your/obsidian-vault
DESKTOP_MCP_CONFIG=desktop-mcp.yaml

DEFAULT_PROJECT_ROOT=/path/to/your/project
CC_ALLOWED_PROJECTS=/path/to/your/project
XCODE_ALLOWED_PROJECTS=/path/to/your/project

ALLOWED_APPS=Obsidian,Xcode,Google Chrome,Safari,Music,Finder,Terminal
APP_ALIASES=chrome=Google Chrome,netease=网易云音乐,网易云=网易云音乐
APP_PROCESS_ALIASES=网易云音乐=网易云音乐|NetEaseMusic|NeteaseMusic
APP_AUTOMATION_ALIASES=网易云音乐=NeteaseMusic

DESKTOP_MCP_STATE_DB=~/.local/share/xiaozhi-desktop-mcp/state.db
DESKTOP_MCP_PENDING_TTL_SECONDS=600
DESKTOP_MCP_AUDIT_ENABLED=true
DESKTOP_MCP_BROWSER_CONTROL_ENABLED=true
# 留空允许任意 http(s) 域名；生产环境可配置 example.com,docs.example.com
DESKTOP_MCP_BROWSER_ALLOWED_DOMAINS=

启动普通 HTTP API：

xiaozhi-desktop-http

检查服务：

curl http://127.0.0.1:8765/api/v1/health
curl http://127.0.0.1:8765/api/v1/actions
curl http://127.0.0.1:8765/api/v2/actions

启动标准 MCP Streamable HTTP：

xiaozhi-desktop-mcp-streamable

默认 endpoint：

http://127.0.0.1:8766/mcp

HTTP Dispatch

普通客户端推荐统一调用：

POST /api/v1/dispatch

请求示例：

{
  "request_id": "client-001",
  "action": "desktop_intent",
  "params": {
    "category": "docs",
    "intent": "search",
    "params": {
      "query": "desktop mcp"
    }
  }
}

响应示例：

{
  "success": true,
  "request_id": "client-001",
  "action": "desktop_intent",
  "spoken_message": "找到了 3 条相关笔记。",
  "error_spoken_message": "",
  "error": "",
  "data": {}
}

客户端建议：

  • 成功时读 spoken_message

  • 失败时读 error_spoken_message

  • 调试和结构化数据读 data

  • 日志串联使用 request_id

更多 Java / Python / Go 示例见 Client Examples。

Common Actions

任务

Action

通用桌面意图

desktop_intent

截图 / 窗口截图 / OCR

desktop_screenshot / desktop_window_screenshot / desktop_ocr

UI 能力 / UI 树 / UI 操作

accessibility_capabilities / accessibility_tree / accessibility_action

查看分类能力

category_registry

保存一条记忆

remember

搜索 Obsidian

search_obsidian

新建 / 打开 / 追加笔记

create_note / open_note / append_daily_note

列出允许项目

list_projects

按项目名交给 Claude Code

ask_cc_project

查看 Claude Code 状态

check_cc

让 Claude Code 继续 / 停止

continue_cc / stop_cc

发送 slash 命令 / 切模型

cc_send_slash_command / cc_switch_model

打开 / 关闭 App

app_open / app_close

聚焦 / 查询 App

app_focus / app_status

浏览器打开 / 搜索

browser_open / browser_search

浏览器标签页 / 当前页

browser_tabs / browser_current

浏览器控制 / 能力

browser_control / browser_capabilities

音乐控制 / 状态 / 音量

music_control / music_status / music_set_volume

网易云客户端搜索

music_search_app

App Driver 能力

app_capabilities

工作流计划 / 执行 / 查询 / 取消

workflow_plan / workflow_execute / workflow_get / workflow_cancel

审计记录

audit_list

Xcode 构建 / 测试 / 清理

xcode_build / xcode_test / xcode_clean

查看 Xcode 最近错误

xcode_last_errors

创建 / 确认待执行动作

pending_create / pending_confirm

桌面环境自检

health

查看工具目录

tool_catalog

Voice Examples

小智，记一下：这个项目先做成桌面 MCP。
小智，打开这个项目的 Claude Code。
小智，把这个任务交给 cc：检查 README 是否清楚。
小智，让 cc 执行 /status。
小智，看看 cc 现在卡在哪。
小智，搜索 Obsidian 里关于桌面 MCP 的笔记。
小智，打开 Xcode 项目并构建。
小智，音乐下一首。
小智，用浏览器搜索 desktop mcp。
小智，列出 Chrome 的标签页。
小智，切到 Chrome 第二个标签页。
小智，看看 Apple Music 正在播放什么。
小智，在网易云音乐客户端搜索周杰伦。
小智，把这段话复制到剪贴板。

Security Model

边界

策略

任意 shell

不提供

App

只能操作 ALLOWED_APPS

项目

只能进入 CC_ALLOWED_PROJECTS

Xcode

只能操作 XCODE_ALLOWED_PROJECTS

Obsidian

只能访问 OBSIDIAN_VAULT

Finder

只能打开 Obsidian、任务目录、允许项目内路径

Accessibility

窗口/UI 目标必须是白名单 App；UI 写操作必须单独确认

中风险动作

先创建 pending action，确认后执行

HTTP 鉴权

非 localhost 绑定必须设置 DESKTOP_MCP_AUTH_TOKEN

可观测性

请求和工具调用记录 request id、状态、耗时，不打印 token

HTTP API 和 Streamable HTTP 都支持：

Authorization: Bearer <token>
X-Desktop-Mcp-Token: <token>

更多细节见 Security Model。

Project Structure

路径

作用

src/xiaozhi_desktop_mcp/server.py

标准 MCP stdio / Streamable HTTP 工具入口

src/xiaozhi_desktop_mcp/http_server.py

FastAPI HTTP 服务

src/xiaozhi_desktop_mcp/api_v1.py

多语言统一 dispatch API

src/xiaozhi_desktop_mcp/api_v2.py

Schema、策略、错误码和审计执行入口

src/xiaozhi_desktop_mcp/storage.py

pending、workflow、audit SQLite 状态库

src/xiaozhi_desktop_mcp/workflows_v2.py

可恢复多步骤工作流

src/xiaozhi_desktop_mcp/tools/

Obsidian、App、cc、项目、Xcode、pending actions 等工具

desktop-mcp.yaml

通用桌面 category registry 配置

docs/api.md

HTTP API 协议

docs/clients.md

Java / Python / Go 示例

docs/operations.md

启动、检查和排障

docs/security.md

安全模型

Development

. .venv/bin/activate
pytest
ruff check src tests

Documentation

文档

内容

API

HTTP API 协议、鉴权、请求响应

Client Examples

Java / Python / Go 接入示例

Operations

启动、健康检查、常见排障

Security

白名单、路径限制、鉴权和日志

Desktop Control Roadmap

完整 LLM 桌面操控差距、当前进度和后续闭环路线

Xiaozhi Integration

小智服务和 MCP bridge 接入

Changelog

版本变化

License

MIT

Install Server
A
license - permissive license
C
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jijiutong/xiaozhi-desktop-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server