Keynote Mcp

Keynote MCP

一个通过 AppleScript 自动化，让 AI 完全控制 Apple Keynote 的 MCP 服务。使用自然语言创建、编辑和导出演示文稿。

附带一个 Claude Skill，其中包含布局规则、字体问题解决方法和设计模式，让演示文稿一次就能达到预期效果。

快速开始

前提条件

• macOS 10.14+
• 已安装 Keynote 应用程序
• Python 3.10+

选项 A：从 PyPI 安装

pip install keynote-mcp

也可以使用 uvx 直接运行（无需安装）：

uvx keynote-mcp

选项 B：从源代码安装

git clone https://github.com/ByAxe/keynote-mcp.git
cd keynote-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

注册 MCP 服务

Claude Code（通过 PyPI 安装 / uvx）：

claude mcp add keynote-mcp keynote-mcp

Claude Code（从源代码安装）：

claude mcp add keynote-mcp "bash -c cd $(pwd) && .venv/bin/python -m keynote_mcp"

Claude Desktop — 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "keynote-mcp": {
      "command": "keynote-mcp",
      "env": {
        "UNSPLASH_KEY": "your_key_here"
      }
    }
  }
}

如果使用 uvx，也可以这样配置：

{
  "mcpServers": {
    "keynote-mcp": {
      "command": "uvx",
      "args": ["keynote-mcp"],
      "env": {
        "UNSPLASH_KEY": "your_key_here"
      }
    }
  }
}

其他 MCP 客户端：

• 命令：keynote-mcp（通过 pip 安装时）或 uvx keynote-mcp
• 传输方式：stdio

3. 安装 Skill（推荐）

keynote-presentation Skill 会教 Claude 如何正确使用 MCP 工具，包括处理字体裁切错误、主题问题、坐标计算和设计模式。

Claude Code — 将 Skill 文件夹复制到你的 skills 目录：

cp -r skills/keynote-presentation ~/.claude/skills/keynote-presentation

Claude.ai：

1. 将 skills/keynote-presentation 文件夹压缩成 zip 文件
2. 前往 Settings > Capabilities > Skills
3. 点击 "Upload skill" 并选择 zip 文件

4. macOS 权限

• System Settings > Privacy & Security > Accessibility — 添加 Terminal/你的 IDE
• System Settings > Privacy & Security > Automation — 允许 Python 控制 Keynote

安全提示： 辅助功能权限是按二进制文件授予的，而不是按项目授予的。授予 python 辅助功能权限后，所有 Python 进程都会共享该权限。大多数 keynote-mcp 工具使用普通 AppleScript（无需辅助功能权限）——只有构建动画时才需要该权限。如需更严格的隔离，可以构建独立二进制文件（见下文的独立二进制文件），这样 keynote-mcp 就能拥有自己的权限条目。

5. 使用

"Create a presentation about our Q1 results with 6 slides"
"Add a slide with a code example showing the API"
"Export the presentation as PDF"

可用工具（30+）

类别	工具
演示文稿	创建、打开、保存、关闭、列出、主题、分辨率、幻灯片尺寸
幻灯片	添加、删除、复制、移动、选择、布局、幻灯片信息
内容	文本框（可控制字体/颜色）、标题、副标题、项目符号列表、编号列表、代码块（可设置颜色）、引言、图片、形状（可设置不透明度）、编辑、删除、移动、调整元素大小、设置元素不透明度、清除幻灯片、演讲者备注、构建动画（通过 UI 脚本添加/移除）
导出	幻灯片截图、导出 PDF
Unsplash	搜索图片、添加到幻灯片、随机图片（需要 UNSPLASH_KEY）

Unsplash 集成（可选）

cp env.example .env
# Add your key from https://unsplash.com/developers
# UNSPLASH_KEY=your_access_key

关于技能

keynote-presentation 技能（skills/keynote-presentation/）解决了在生产环境中发现的实际问题：

• 字体裁切错误：较大的字号（>48pt）会创建极小的文本框，导致文本被裁切到仅剩 1-2 个字符。该技能教会 Claude 使用先调整大小再编辑的变通方法。
• 主题陷阱：许多主题（Gradient、Minimalist Dark）在空白幻灯片上不会显示背景。该技能提供了经过测试的兼容性表。
• 坐标计算：没有文本对齐属性。该技能提供了逐字符宽度估算值，便于手动居中。
• 形状填充限制：无法通过 AppleScript 写入形状填充颜色。该技能记录了适用于深色主题容器的不透明度变通方法。
• 深色主题颜色参考：经过测试的 RGB 值，适用于白色文本、灰色副标题、绿色代码注释和蓝色章节标题。
• 双栏布局：使用 add_shape 容器实现左侧代码、右侧项目符号的幻灯片布局，并提供经过验证的坐标。
• 设计模式：仿落地页的幻灯片模板（主视觉、陈述、项目符号、代码演示、结尾），并提供经过测试的位置。

技能结构

skills/keynote-presentation/
    SKILL.md                              # Main skill file with YAML frontmatter
    references/
        theme-reference.md                # Theme compatibility table
        coordinate-reference.md           # Layout math and centering formulas

项目结构

src/
  keynote_mcp/
    __init__.py            # Package version
    __main__.py            # python -m keynote_mcp entry point
    server.py              # MCP server — routes tool calls via stdio
    tools/
      presentation.py      # Presentation lifecycle tools
      slide.py             # Slide management tools
      content.py           # Content creation and editing tools
      export.py            # Screenshot and PDF export tools
      unsplash.py          # Unsplash image integration
    utils/
      applescript_runner.py # Executes AppleScript via osascript
      error_handler.py     # Exception hierarchy and validation
    applescript/           # AppleScript source files
skills/                    # Claude Skills for this MCP
tests/                     # Test scaffolding

独立二进制文件

对于注重安全、不想向共享的 python 二进制文件授予辅助功能权限的用户，可以将 keynote-mcp 构建为拥有独立权限条目的独立可执行文件：

# Install pyinstaller
pip install pyinstaller

# Build standalone binary (~31MB)
pyinstaller --onefile --name keynote-mcp src/keynote_mcp/__main__.py

# Code-sign so macOS tracks it as its own app
codesign -s - -f dist/keynote-mcp

然后在 MCP 配置中使用该二进制文件：

{
  "mcpServers": {
    "keynote-mcp": {
      "command": "/absolute/path/to/dist/keynote-mcp"
    }
  }
}

授予辅助功能权限后，它会显示为“keynote-mcp”，而不是“Python”。

贡献

详情请参阅 CONTRIBUTING.md。

许可证

MIT — 参阅 LICENSE。

致谢

• Model Context Protocol — 面向 AI 的标准化工具协议
• Unsplash — 免费的高质量图片
• AppleScript — macOS 自动化
• 原始项目由 easychen 创建