MCP桌面应用程序PoC
概念验证显示MCP服务器与本地macOS桌面应用程序通信——通过双向通信读取实时数据并控制应用程序的显示。Claude Desktop可以问“现在几点了？”或说“切换到12小时制”，Mac上的实时时钟就会响应。
先决条件
假设这些已安装：
- Xcode 16+ （使用命令行工具）
- Python 3.10+
- Node.js/npx
您还需要：
- Xcodegen --
brew install xcodegen - 紫外线 --
curl -LsSf https://astral.sh/uv/install.sh | sh
快速开始
1.克隆仓库
git clone
cd mcp-app-poc2.构建桌面应用程序
cd TimeClockApp
xcodegen generate
xcodebuild -project TimeClockApp.xcodeproj \
-scheme TimeClockApp \
-configuration Release \
build \
CONFIGURATION_BUILD_DIR=./build/Release
cd ..3.启动桌面应用程序
open TimeClockApp/build/Release/TimeClockApp.app点击 启动服务器 在应用程序UI中。
4.验证HTTP端点
curl -s http://127.0.0.1:8765/time | python3 -m json.tool您应该看到：
{
"iso": "2026-03-25T14:30:05+09:00",
"unix": 1742880605,
"human": "14:30:05",
"timezone": "Asia/Tokyo"
}5.配置克劳德桌面
编辑（或创建） ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"timeclock-server": {
"command": "/Users/YOUR_USERNAME/.local/bin/uv",
"args": [
"--directory",
"/absolute/path/to/timeclock-server",
"run",
"server.py"
]
}
}
}替换两个占位符值：
| 占位符 | 如何找到真正的价值 |
|---|---|
/Users/YOUR_USERNAME/.local/bin/uv | 快跑 which uv 在您的终端 |
/absolute/path/to/timeclock-server | 快跑 pwd 从 timeclock-server/ 目录 |
6.重新启动克劳德桌面
完全退出克劳德桌面 Cmd+Q （关闭窗口是不够的），然后重新启动它。
7.问克劳德
打开克劳德桌面，键入：
现在几点？
克劳德会打电话给 get_time MCP工具，从正在运行的桌面应用程序中读取时间并返回。
您还可以控制时钟显示。尝试：
将时钟设置为纽约时间，并切换为12小时制
克劳德会打电话给 set_timezone 和 set_time_format 更改实时时钟显示的工具。
建筑
┌──────────────────┐ stdio ┌──────────────────────┐
│ Claude Desktop │ ◄──────────────────► │ timeclock-server │
│ (MCP Client) │ (MCP protocol) │ (Python MCP Server) │
└──────────────────┘ └─────────┬────────────┘
│
┌─────────▼──────────────────────┐
│ GET /time │
│ GET /clock/settings │
│ POST /clock/format │
│ POST /clock/seconds │
│ POST /clock/timezone │
│ POST /clock/date │
└─────────┬──────────────────────┘
│ HTTP
┌─────────▼────────────┐
│ TimeClockApp │
│ (macOS SwiftUI App) │
│ localhost:8765 │
└──────────────────────┘数据流：
阅读（GET）：
- 你问克劳德桌面一个问题，比如“现在几点了？”
- Claude Desktop称
get_time通过stdio在MCP服务器上安装工具 - MCP服务器向以下对象发出HTTP GET请求
http://127.0.0.1:8765/time - TimeClockApp以JSON格式返回当前时间
- MCP服务器格式化响应并将其返回给Claude Desktop
- 克劳德在聊天中给出了答案
控制（POST）：
- 您要求Claude更改设置（例如，“切换到12小时制”）
- Claude调用适当的MCP工具（例如。，
set_time_format(format="12h")) - MCP服务器POS
{"format": "12h"}到http://127.0.0.1:8765/clock/format - TimeClockApp会立即更新其实时显示，并以当前设置JSON进行响应
- MCP服务器格式化设置并将其返回给Claude Desktop
- Claude向用户确认更改
运作原理
时钟应用程序 是macOS SwiftUI的原生应用程序。它显示实时时钟并运行嵌入式HTTP服务器（由 更迅速)在端口8765。这 /time endpoint以多种格式（ISO 8601、人类可读、Unix纪元和时区）返回当前时间。POST端点(/clock/format, /clock/seconds, /clock/timezone, /clock/date)实时更改显示设置，并以JSON格式返回完整的更新设置。
时钟服务器 是一个Python MCP服务器，使用官方 mcp SDK。它公开了六个工具： get_time 和 get_clock_settings 阅读，加 set_time_format, toggle_seconds, set_timezone，以及 toggle_date 用于控制显示器。它通过stdio传输进行通信，这是本地运行MCP服务器的标准。
克劳德桌面 是MCP客户端。上面写着 claude_desktop_config.json 在启动时，将MCP服务器作为子进程启动，并在用户提出相关问题时通过stdio进行工具调用。
双向通信（v1.1）
除了读取时间，Claude还可以使用写入工具实时控制时钟显示。
工作示例： “将时钟设置为纽约时间，并切换为12小时制。”
- 克劳德打电话来
set_timezone(timezone="America/New_York") - MCP服务器POS
{"timezone": "America/New_York"}到http://127.0.0.1:8765/clock/timezone - TimeClock桌面应用程序更新其实时显示，并以JSON格式返回完整的当前设置
- MCP服务器格式化响应并将其返回给Claude
- 克劳德打电话来
set_time_format(format="12h") - 格式更改时重复步骤2-4
- 克劳德确认：“完成。时钟现在显示东部时间为12小时制。”
端点参考：
| 端点 | 方法 | 请求体 | 响应 | |
|---|---|---|---|---|
/time | 获取 | -- | {iso, unix, human, timezone} | |
/clock/settings | 获取 | -- | {format, seconds_visible, date_visible, timezone, is_local_timezone} | |
/clock/format | 职位 | `{"format": "12h"\ | "24h"}` | 完整设置JSON |
/clock/seconds | 职位 | `{"visible": true\ | false}` | 完整设置JSON |
/clock/timezone | 职位 | {"timezone": ""} | 完整设置JSON | |
/clock/date | 职位 | `{"visible": true\ | false}` | 完整设置JSON |
所有POST端点在成功时返回具有完整设置的HTTP 200，无效输入返回HTTP 400。
项目结构
mcp-app-poc/
├── TimeClockApp/ # macOS SwiftUI desktop app
│ ├── project.yml # XcodeGen project spec
│ ├── Sources/
│ │ ├── TimeClockApp.swift
│ │ ├── TimeClockApp.entitlements
│ │ ├── Model/
│ │ │ ├── ClockSettings.swift
│ │ │ └── TimeResponse.swift
│ │ ├── ViewModel/
│ │ │ └── AppViewModel.swift
│ │ └── Views/
│ │ ├── ClockDisplayView.swift
│ │ └── ContentView.swift
│ └── README.md # Component docs
├── timeclock-server/ # Python MCP server
│ ├── server.py # MCP server with 6 tools (read + control)
│ ├── pyproject.toml # Dependencies (httpx, mcp)
│ ├── tests/
│ │ └── test_server.py
│ └── README.md # Component docs
└── README.md # This file组件详情
- 时钟应用程序自述 --构建步骤、HTTP端点引用、已知约束
- 时钟服务器README --设置、测试、MCP检查员、工具参考
扩展此模式
此PoC演示了一个通用模式： MCP服务器作为桌面应用程序的桥梁。要使其适应不同的用例：
- 替换桌面应用程序 使用任何公开HTTP API（或向现有应用程序添加HTTP层）的应用程序
- 添加新的MCP工具 在
server.py调用应用程序的端点 - 更新Claude桌面配置 指向您的服务器
该模式适用于任何可以通过HTTP提供数据的桌面应用程序——生产力工具、媒体播放器、系统实用程序或自定义业务软件。
故障排除
端口8765已在使用中
lsof -i :8765终止冲突进程，然后重新启动TimeClockApp服务器。
macOS防火墙弹出窗口
首次启动时，macOS可能会要求允许传入网络连接。点击 允许。如果您关闭了对话框，请转到 系统设置>网络>防火墙>选项 并添加应用程序。
克劳德桌面：MCP服务器未出现
这 command 领域 claude_desktop_config.json 必须是 绝对路径 到 uv.光秃秃的 uv 将失败，因为Claude Desktop在不继承shell PATH的情况下生成子进程。
which uv # Use this output as the "command" valueClaude Desktop：服务器无法启动
这 --directory 论点必须是 绝对路径 到 timeclock-server/ 目录。相对路径将不起作用，因为Claude Desktop子流程的工作目录是不可预测的。
Claude Desktop：配置更改未生效
克劳德桌面必须 完全退出 （Cmd+Q）并重新启动。关闭窗口不会退出macOS上的应用程序——配置仅在启动时读取。
沙盒网络.服务器权限
这 com.apple.security.network.server 权限已在中配置 project.yml。如果您修改了权限文件，而HTTP服务器停止工作，请验证此权限是否仍然存在。
检查MCP日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log这显示了Claude Desktop和MCP服务器之间的原始通信，可用于诊断启动失败或工具调用错误。