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 スキルは、フォントのクリッピングバグ、テーマの落とし穴、座標計算、デザインパターンへの対応など、MCP ツールを正しく使う方法を Claude に教えます。

Claude Code — スキルフォルダーをスキルディレクトリにコピーします：

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 のアクセス許可

• システム設定 > プライバシーとセキュリティ > アクセシビリティ — Terminal／使用する IDE を追加します
• システム設定 > プライバシーとセキュリティ > オートメーション — 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 など、多くのテーマでは Blank スライドに背景が表示されません。このスキルには、テスト済みの互換性一覧が含まれています。
• 座標の計算：テキスト配置プロパティはありません。このスキルでは、手動で中央揃えするための文字ごとの幅の推定値を提示します。
• 図形の塗りつぶしの制限：図形の塗りつぶし色は AppleScript では書き込めません。このスキルでは、ダークテーマのコンテナ向けに不透明度を使う回避策を説明します。
• ダークテーマのカラーリファレンス：白いテキスト、グレーのサブタイトル、緑色のコードコメント、青いセクション見出しに使用する、テスト済みの RGB 値を示します。
• 2カラムレイアウト：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"
    }
  }
}

アクセシビリティ権限を付与すると、「Python」ではなく「keynote-mcp」として表示されます。

貢献

詳しくは CONTRIBUTING.md をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。

謝辞

• Model Context Protocol — AI 向けに標準化されたツールプロトコル
• Unsplash — 無料の高品質画像
• AppleScript — macOS の自動化
• easychen によるオリジナルプロジェクト