AI导哈

macOS快捷方式MCP服务器

一个允许ChatGPT兼容客户端触发原生macOS快捷方式的轻量级MCP服务器。

  • by CaseyRo
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 CaseyRo/mac_shortcuts_mcp

使用说明

mac_shortcuts_mcp

概述

mac_shortcuts_mcp 是一个最小的MCP（模型上下文协议）服务器，允许ChatGPT兼容的客户端触发本地macOS快捷方式。它包裹着 shortcuts CLI支持模式感知MCP工具，因此助手可以执行命名快捷方式、传递可选文本输入并接收结构化结果。

目录

先决条件

  • 带有Shortcuts应用程序的macOS主机 shortcuts 命令行工具在中可用 PATH.
  • Python 3.12或更高版本，外加 紫外线 用于依赖性管理。
  • FastMCP （通过自动安装 uv)提供流线型MCP转轮。

安装

初始设置

uv sync

拉取更改后进行更新

跑 uv sync 每当你 git pull 新的承诺。该命令读取项目的 pyproject.toml/uv.lock 并确保虚拟环境完全匹配——安装新的依赖项、更新现有的依赖项，并删除不再需要的任何内容。除非您有意清除缓存的轮子，否则不需要额外的清理(uv cache prune)或者从头开始重建环境。

运行服务器

快速入门（STDIO）

uv run fastmcp run src/mac_shortcuts_mcp/server.py --transport stdio

这将在STDIO模式下使用推荐的FastMCP CLI启动MCP服务器。配置您的客户端以执行确切的命令，并通过stdin/stdout上的JSON-RPC进行通信。

可流式传输HTTP/SSE

uv run fastmcp run src/mac_shortcuts_mcp/server.py \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000
  • 使用 --transport http 相反，当您需要JSON响应而不是SSE流时。
  • 调整 --host/--port 以匹配您的网络环境。

客户端集成

大多数MCP客户端都期望生成STDIO进程或HTTP端点。FastMCP运行程序使用上述命令公开两者。

STDIO客户端

  1. 使用启动服务器 快速开始 命令。
  2. 配置客户端以运行确切的命令并保持进程活动。
  3. 客户端应通过stdin/stdout发送和接收JSON-RPC帧。

HTTP/SSE客户端

  1. 使用启动服务器 可流式传输HTTP/SSE 命令。
  2. 向客户指出 http://$HOST:$PORT/mcp （使用 https:// 在其他地方终止TLS时）。
  3. 选择SSE作为流式响应，或选择JSON作为离散响应。

工具有效载荷示例

在调用公开的工具时，向MCP客户端提供如下有效负载：

{
  "shortcutName": "Show Content",
  "textInput": "testing output",
  "timeoutSeconds": 30
}
  • shortcutName 选择要执行的macOS快捷方式。
  • textInput （可选）将文本传输到快捷方式的标准输入，镜像 `echo "value" | shortcuts run "Shortcut Name"`.
  • timeoutSeconds 限制执行时间以防止进程失控。

高级配置

FastMCP运行器在没有TLS的情况下绑定，并禁用DNS重新绑定保护。对于HTTPS终止或强制执行 allowed_hosts / allowed_origins 策略中，请改用基于Typer的CLI：

uv run python -m mac_shortcuts_mcp http \
  --host 0.0.0.0 \
  --port 8443 \
  --allowed-host example.com \
  --allowed-origin https://example.com \
  --certfile /path/to/fullchain.pem \
  --keyfile /path/to/privkey.pem
  • 省略 --certfile/--keyfile 仅提供HTTP服务，或更改 --host 到 127.0.0.1 当通过反向代理终止TLS时。
  • 提供多种 --allowed-host / --allowed-origin 根据需要标记以重新启用FastMCP的DNS重新绑定保护。

相关 MCP