Metadata-Version: 2.4
Name: keynote-mcp
Version: 1.0.0
Summary: An MCP server for controlling Apple Keynote presentations via AppleScript
Home-page: https://github.com/easychen/keynote-mcp
Author: easychen
Author-email: easychen <easychen@gmail.com>
Maintainer-email: easychen <easychen@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/easychen/keynote-mcp
Project-URL: Repository, https://github.com/easychen/keynote-mcp
Project-URL: Documentation, https://github.com/easychen/keynote-mcp/blob/main/docs/README.md
Project-URL: Bug Reports, https://github.com/easychen/keynote-mcp/issues
Project-URL: Changelog, https://github.com/easychen/keynote-mcp/blob/main/CHANGELOG.md
Keywords: keynote,mcp,model-context-protocol,applescript,automation,presentation,macos,ai,llm
Platform: macOS
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Classifier: Topic :: Office/Business :: Office Suites
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: aiofiles>=0.8.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: flake8>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: safety>=2.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Requires-Dist: coverage>=6.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=5.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == "docs"
Provides-Extra: build
Requires-Dist: build>=0.8.0; extra == "build"
Requires-Dist: twine>=4.0.0; extra == "build"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: platform
Dynamic: requires-python

# Keynote MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/keynote-mcp.svg)](https://pypi.org/project/keynote-mcp/)
[![macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)

An MCP server that gives AI full control over Apple Keynote through AppleScript automation. Create, edit, and export presentations — all via natural language.

Ships with a **Claude Skill** that encodes layout rules, font workarounds, and design patterns so presentations come out right on the first try.

## Quick Start

### Prerequisites

- macOS 10.14+
- Keynote application installed
- Python 3.10+

### Option A: Install from PyPI

```bash
pip install keynote-mcp
```

Or run directly with `uvx` (no install needed):
```bash
uvx keynote-mcp
```

### Option B: Install from source

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

### Register the MCP server

**Claude Code (PyPI install / uvx):**
```bash
claude mcp add keynote-mcp keynote-mcp
```

**Claude Code (from source):**
```bash
claude mcp add keynote-mcp "bash -c cd $(pwd) && .venv/bin/python -m keynote_mcp"
```

**Claude Desktop** — add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "keynote-mcp": {
      "command": "keynote-mcp",
      "env": {
        "UNSPLASH_KEY": "your_key_here"
      }
    }
  }
}
```

Or if using `uvx`:
```json
{
  "mcpServers": {
    "keynote-mcp": {
      "command": "uvx",
      "args": ["keynote-mcp"],
      "env": {
        "UNSPLASH_KEY": "your_key_here"
      }
    }
  }
}
```

**Other MCP clients:**
- Command: `keynote-mcp` (if installed via pip) or `uvx keynote-mcp`
- Transport: stdio

### 3. Install the Skill (recommended)

The `keynote-presentation` skill teaches Claude how to use the MCP tools correctly — handling font clipping bugs, theme pitfalls, coordinate math, and design patterns.

**Claude Code** — copy the skill folder to your skills directory:
```bash
cp -r skills/keynote-presentation ~/.claude/skills/keynote-presentation
```

**Claude.ai:**
1. Zip the `skills/keynote-presentation` folder
2. Go to Settings > Capabilities > Skills
3. Click "Upload skill" and select the zip

### 4. macOS permissions

- System Settings > Privacy & Security > Accessibility — add Terminal/your IDE
- System Settings > Privacy & Security > Automation — allow Python to control Keynote

### 5. Use it

```
"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"
```

## Available Tools (30+)

| Category | Tools |
|----------|-------|
| **Presentation** | create, open, save, close, list, themes, resolution, slide size |
| **Slides** | add, delete, duplicate, move, select, layouts, slide info |
| **Content** | text boxes, titles, subtitles, bullet lists, numbered lists, code blocks, quotes, images, edit, delete, move, resize elements, speaker notes |
| **Export** | screenshot slides, export PDF |
| **Unsplash** | search images, add to slides, random images (requires `UNSPLASH_KEY`) |

## Unsplash Integration (optional)

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

## About the Skill

The `keynote-presentation` skill (`skills/keynote-presentation/`) solves real problems discovered through production use:

- **Font clipping bug**: Large font sizes (>48pt) create tiny text boxes that clip text to 1-2 characters. The skill teaches Claude the resize-then-edit workaround.
- **Theme pitfalls**: Many themes (Gradient, Minimalist Dark) don't show backgrounds on Blank slides. The skill includes a tested compatibility table.
- **Coordinate math**: No text-align property exists. The skill provides per-character width estimates for manual centering.
- **Design patterns**: Landing-page-style slide templates (hero, statement, bullets, code demo, closing) with tested positions.

### Skill structure

```
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
```

## Project Structure

```
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
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

MIT — see [LICENSE](LICENSE).

## Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) — standardized tool protocol for AI
- [Unsplash](https://unsplash.com/) — free high-quality images
- [AppleScript](https://developer.apple.com/documentation/applescript) — macOS automation
- Original project by [easychen](https://github.com/easychen/keynote-mcp)
