Xiaozhi Desktop MCP
Xiaozhi Desktop MCP is a secure Mac desktop automation server that exposes local capabilities as controlled MCP/HTTP tools, enforcing safety via allowlists, path restrictions, token authentication, and user confirmation for risky operations.
Obsidian / Notes
Save memories, create/open/append notes (including daily notes), search vault, and retrieve recent memories.
App Control
Open, close, focus, or query macOS apps from a configurable allowlist.
Claude Code / Codex Session Management
Start, open, list, clean up, and stop sessions; check status; focus windows; send natural language instructions, yes/no/cancel decisions, and slash commands (
/init,/compact,/model); switch models.
Project-Aware Shortcuts
List allowed projects, resolve project paths, open Claude Code for a named project, send tasks, and check/continue/focus/stop CC via voice-friendly shortcuts.
Xcode Automation
Open allowlisted projects/workspaces, build, test, clean, and retrieve recent build errors.
Browser, Finder & Clipboard
Open URLs, perform browser searches, locate items in Finder, and read/write the clipboard.
Music Control
Play, pause, skip tracks, and search for music.
Pending Actions (Safety Gate)
Create medium-risk actions requiring user confirmation before execution; list, confirm, or cancel them.
Universal Intent Routing
Route any capability via a unified
category + intentinterface (desktop_intent) and query available categories.
Diagnostics & Observability
Health checks, redacted config summaries, full tool catalog, and request tracing.
Allows opening or closing the Google Chrome app on macOS via app control.
Provides tools to save memories, append notes, manage daily notes, search, and read recent notes within an Obsidian vault.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Xiaozhi Desktop MCP Save a memory to Obsidian: meeting recap"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 · 4.0 Upgrade Plan · 4.0 Migration · macOS E2E · 3.0 Migration · Client Examples · Operations · Security · Xiaozhi Integration
License: MIT · Version: 4.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-sys-assist
Why This Exists
语音助手和 LLM 真正接入桌面时,难点不是“能不能调用命令”,而是“能不能安全、稳定、可追踪地调用本机能力”。
这个项目把桌面自动化里的风险收束成明确规则:
App、项目、Xcode、Obsidian 都有白名单或路径边界
中风险动作先进入 pending action,再由用户确认
MCP Client 可以走标准协议,普通程序可以走 HTTP API
每次请求都有 request id,方便从客户端追到工具调用
HTTP 暴露到非 localhost 时必须开启 token 鉴权
Transports
入口 | 命令 | 默认地址 | 适合场景 |
MCP stdio |
| 标准输入输出 | Claude Desktop、小智 bridge、本机 MCP client |
MCP Streamable HTTP |
|
| 支持 MCP over HTTP 的客户端 |
HTTP API v1 |
|
| Java / Python / Go / 稳定客户端 |
HTTP 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 | 从 |
Apps | 打开、关闭、聚焦或查询 |
Xcode | 打开项目、build、test、clean、查看最近错误 |
Browser / Finder / Clipboard | 标签页读取与控制、打开搜索、Finder 定位、剪贴板读写 |
Desktop Perception | 全屏/窗口截图、macOS Vision OCR、MCP 图像内容 |
Accessibility UI | UI 树、元素状态,以及确认后的点击、输入、滚动、拖拽、菜单和文件选择 |
Verified Execution | 短期 Observation、窗口/目标重校验、幂等动作和操作后自动验证 |
Music | Apple Music 状态/音量控制、网易云播放和客户端内搜索 |
Pending Actions | SQLite 持久化、TTL、原子确认、防重复执行 |
Workflows | 多步骤计划、暂停确认、重启恢复、继续和取消 |
Dynamic Workflows | 只读重试、受限等待、条件分支和显式安全补偿 |
Audit | SQLite 脱敏审计,只保存参数名,不保存参数值 |
Diagnostics | 健康检查、配置摘要、工具目录、会话清理 |
Observability |
|
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_OBSERVATION_TTL_SECONDS=120
DESKTOP_MCP_WORKFLOW_LEASE_SECONDS=300
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/mcpHTTP 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 |
通用桌面意图 |
|
截图 / 窗口截图 / OCR |
|
创建短期桌面观察 |
|
重校验、执行一次并验证 |
|
UI 能力 / UI 树 / UI 操作 |
|
查看分类能力 |
|
保存一条记忆 |
|
搜索 Obsidian |
|
新建 / 打开 / 追加笔记 |
|
列出允许项目 |
|
按项目名交给 Claude Code |
|
查看 Claude Code 状态 |
|
让 Claude Code 继续 / 停止 |
|
发送 slash 命令 / 切模型 |
|
打开 / 关闭 App |
|
聚焦 / 查询 App |
|
浏览器打开 / 搜索 |
|
浏览器标签页 / 当前页 |
|
浏览器控制 / 能力 |
|
音乐控制 / 状态 / 音量 |
|
网易云客户端搜索 |
|
App Driver 能力 |
|
工作流计划 / 执行 / 查询 / 取消 |
|
审计记录 |
|
Xcode 构建 / 测试 / 清理 |
|
查看 Xcode 最近错误 |
|
创建 / 确认待执行动作 |
|
桌面环境自检 |
|
查看工具目录 |
|
Voice Examples
小智,记一下:这个项目先做成桌面 MCP。
小智,打开这个项目的 Claude Code。
小智,把这个任务交给 cc:检查 README 是否清楚。
小智,让 cc 执行 /status。
小智,看看 cc 现在卡在哪。
小智,搜索 Obsidian 里关于桌面 MCP 的笔记。
小智,打开 Xcode 项目并构建。
小智,音乐下一首。
小智,用浏览器搜索 desktop mcp。
小智,列出 Chrome 的标签页。
小智,切到 Chrome 第二个标签页。
小智,看看 Apple Music 正在播放什么。
小智,在网易云音乐客户端搜索周杰伦。
小智,把这段话复制到剪贴板。Security Model
边界 | 策略 |
任意 shell | 不提供 |
App | 只能操作 |
项目 | 只能进入 |
Xcode | 只能操作 |
Obsidian | 只能访问 |
Finder | 只能打开 Obsidian、任务目录、允许项目内路径 |
Accessibility | 窗口/UI 目标必须是白名单 App;UI 写操作必须单独确认 |
中风险动作 | 先创建 pending action,确认后执行 |
HTTP 鉴权 | 非 localhost 绑定必须设置 |
HTTP Token 权限 | 用 |
工作流恢复 | 租约防止并发 owner;崩溃后只读步骤可恢复,未知写操作结果会停机 |
可观测性 | 请求和工具调用记录 request id、状态、耗时,不打印 token |
HTTP API 和 Streamable HTTP 都支持:
Authorization: Bearer <token>
X-Desktop-Mcp-Token: <token>更多细节见 Security Model。
Project Structure
路径 | 作用 |
| 标准 MCP stdio / Streamable HTTP 工具入口 |
| FastAPI HTTP 服务 |
| 多语言统一 dispatch API |
| Schema、策略、错误码和审计执行入口 |
| pending、workflow、audit SQLite 状态库 |
| 可恢复多步骤工作流 |
| Obsidian、App、cc、项目、Xcode、pending actions 等工具 |
| 通用桌面 category registry 配置 |
| HTTP API 协议 |
| Java / Python / Go 示例 |
| 启动、检查和排障 |
| 安全模型 |
Development
. .venv/bin/activate
pytest
ruff check src testsDocumentation
文档 | 内容 |
HTTP API 协议、鉴权、请求响应 | |
Java / Python / Go 接入示例 | |
启动、健康检查、常见排障 | |
白名单、路径限制、鉴权和日志 | |
完整 LLM 桌面操控差距、当前进度和后续闭环路线 | |
真实 App smoke 矩阵、运行条件和最近一次结果 | |
小智服务和 MCP bridge 接入 | |
版本变化 |
License
MIT
Available Tools
48 toolsapp_closeA
当用户说“关闭某个 App”时调用;只允许关闭配置白名单里的 macOS App。
Inputs: app_name (required).
app_openA
当用户说“打开某个 App”时调用;只允许打开配置白名单里的 macOS App。
Inputs: app_name (required).
cc_cleanup_sessionsA
清理已经不存在的 Claude Code/Codex 可见会话登记。
Inputs: no named parameters.
cc_close_terminalB
当用户说“关闭终端/关闭cc窗口”时调用,关闭前台 Terminal/iTerm 窗口。
Inputs: terminal.
cc_create_taskB
当用户说“让 cc/Codex/Claude Code 做...”时调用,只创建待办任务,不执行命令。
Inputs: title (required), instruction (required), priority, project_path.
cc_focus_sessionB
把指定 Claude Code/Codex 可见会话窗口拉到前台。
Inputs: session_id.
cc_list_sessionsA
列出当前服务进程记住的可见 Claude Code/Codex 会话。
Inputs: no named parameters.
cc_open_claude_codeC
当用户说“打开 Claude Code/打开 cc”时调用,默认在可见 Terminal 中启动 claude。
Inputs: cli_args, terminal, session_id, project_path.
cc_open_visible_sessionB
打开可见 Terminal/iTerm 窗口并启动 Claude Code/Codex;方便人工观看和接管。
Inputs: cli, cli_args, terminal, session_id, +1 more.
cc_send_decisionC
当 CLI 等待确认时发送 yes/no/cancel;默认允许,可通过配置改成确认或禁止。
Inputs: decision (required), confirm, session_id, allow_frontmost.
cc_send_instructionC
向已启动的受管 CLI 会话发送自然语言任务说明。
Inputs: text (required), session_id, allow_frontmost.
cc_send_slash_commandB
发送 /init、/compact、/model 等内部命令;默认允许,可通过配置收紧。
Inputs: command (required), args, confirm, session_id, +1 more.
cc_session_statusC
查看受管 CLI 当前状态,只读取最近输出:等待确认、报错、完成、运行中或空闲。
Inputs: max_chars, session_id.
cc_start_sessionC
启动受管 Claude Code/Codex CLI 会话;只能在配置允许的项目目录里启动。
Inputs: cli, cli_args, session_id, project_path.
cc_stop_sessionC
停止受管 Claude Code/Codex CLI 会话,并关闭前台 Terminal 窗口。
Inputs: session_id, allow_frontmost.
cc_switch_modelC
切换受管 Claude Code/Codex 会话模型;默认允许所有模型,可用配置收紧。
Inputs: model (required), confirm, session_id, allow_frontmost.
desktop_ask_ccC
语音友好入口:把一句自然语言任务交给 Claude Code/Codex。
Inputs: text (required), cli, terminal, session_id, +3 more.
desktop_ask_cc_projectC
按项目名/别名把任务交给 Claude Code/Codex。
Inputs: text (required), project (required), cli, terminal, +3 more.
desktop_category_registryA
返回通用桌面能力分类,例如 music、docs、ai、dev、browser、system。
Inputs: no named parameters.
desktop_check_ccC
语音友好入口:看看 Claude Code/Codex 当前在做什么或卡在哪。
Inputs: max_chars, session_id.
desktop_config_summaryA
返回脱敏配置摘要,方便排查桌面 MCP 环境。
Inputs: no named parameters.
desktop_continue_ccC
语音友好入口:让 Claude Code/Codex 继续。
Inputs: confirm, session_id, allow_frontmost.
desktop_focus_ccB
语音友好入口:把 Claude Code/Codex 窗口切到前台。
Inputs: session_id.
desktop_health_detailA
诊断桌面 MCP 环境:路径、CLI、终端 App、关键配置。
Inputs: no named parameters.
desktop_intentD
通用桌面意图入口:按 category + intent 路由到底层安全能力。
Inputs: intent (required), category (required), params.
desktop_list_projectsA
列出可以被桌面 MCP 打开的白名单项目。
Inputs: no named parameters.
desktop_open_cc_projectC
语音友好入口:打开某个项目的 Claude Code/Codex 可见窗口。
Inputs: cli, cli_args, terminal, session_id, +1 more.
desktop_open_cc_project_namedC
按项目名/别名打开 Claude Code/Codex 可见窗口。
Inputs: project (required), cli, cli_args, terminal, +1 more.
desktop_rememberC
语音友好入口:当用户说“记一下...”时保存到 Obsidian。
Inputs: text (required), tags.
desktop_resolve_projectA
把项目名、目录名或白名单路径解析为安全项目路径。
Inputs: project (required).
desktop_stop_ccC
语音友好入口:退出 Claude Code/Codex 并关闭窗口。
Inputs: session_id, allow_frontmost.
desktop_tool_catalogA
返回桌面 MCP 工具目录,帮助小智/Java 选择高层工具。
Inputs: no named parameters.
obsidian_append_daily_noteC
追加内容到 Obsidian 每日笔记。
Inputs: text (required), date, folder.
obsidian_append_noteC
追加内容到 Obsidian vault 内指定 Markdown 笔记。
Inputs: text (required), note_path (required), heading.
obsidian_create_noteB
新建 Obsidian vault 内的 Markdown 笔记。
Inputs: note_path (required), text, overwrite.
obsidian_open_noteC
打开 Obsidian vault 内的 Markdown 笔记。
Inputs: note_path (required).
obsidian_recent_memoriesC
读取最近几条语音记忆。
Inputs: limit.
obsidian_save_memoryC
当用户说“记一下/保存想法/写到 Obsidian”时调用,保存一条语音记忆。
Inputs: text (required), tags.
obsidian_searchC
搜索 Obsidian vault 内 Markdown 笔记,返回少量片段。
Inputs: query (required), limit.
pending_action_cancelC
取消一个待确认动作,不执行。
Inputs: action_id (required).
pending_action_confirmC
确认并执行一个待确认动作。
Inputs: action_id (required).
pending_action_createA
创建一个待确认动作;只允许白名单动作类型,不会立即执行。
Inputs: action_type (required), title, params.
pending_action_listB
列出待确认动作;status 为空时列出全部。
Inputs: status.
xcode_buildC
在白名单项目内执行 xcodebuild build。
Inputs: scheme, xcode_path, destination, project_path, +1 more.
xcode_cleanC
在白名单项目内执行 xcodebuild clean。
Inputs: scheme, xcode_path, destination, project_path, +1 more.
xcode_last_errorsC
读取最近一次 xcodebuild 输出中的错误线索。
Inputs: limit.
xcode_open_projectB
打开白名单项目内的 .xcodeproj 或 .xcworkspace。
Inputs: xcode_path, project_path.
xcode_testC
在白名单项目内执行 xcodebuild test。
Inputs: scheme, xcode_path, destination, project_path, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Many tools have overlapping purposes, especially among 'cc_' and 'desktop_' prefixes (e.g., cc_open_claude_code, cc_start_session, desktop_open_cc_project, desktop_open_cc_project_named). An agent could easily misselect which tool to use for launching or managing Claude Code sessions.
Tool names follow a consistent verb_noun pattern within each subsystem (app_, cc_, obsidian_, xcode_), but the overall mix of prefixes and some near-duplicate names (e.g., cc_open_claude_code vs cc_open_visible_session) cause minor confusion.
With 48 tools, the set is quite large but covers a broad domain (desktop automation, Claude Code, Obsidian, Xcode). However, many tools serve very similar functions, suggesting some could be consolidated.
The tool set provides comprehensive coverage for its intended domain: app management, Claude Code lifecycle, Obsidian note operations, pending actions, and Xcode build/test. Minor gaps exist (e.g., lack of file system operations), but core workflows are well-supported.
Maintenance
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP server that enables AI to fully control macOS — mouse, keyboard, terminal, screenshots, window management, UI element detection, and provides AI-optimized information reporting.3630 npmMIT
- AlicenseNot gradedqualityDmaintenanceA secure, constraint-based macOS OS-level automation MCP server for AI assistants.MIT
- AlicenseBqualityDmaintenanceProvides a local MCP bridge for AI assistants to control a Mac by observing screen state and performing actions like mouse movement, clicking, typing, and opening URLs.12MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that bridges Claude Desktop to iCloud Mail, Calendar, Reminders, and Contacts, enabling cross-service actions like daily briefs, scheduling, email drafting, task deferring, and unified search via a single prompt.273 npmMIT