keynote

Keynote-MCP exposes a Python-based MCP server that automates AppleScript-driven Keynote control. Once the server is running, you can connect via an MCP client to issue natural language actions that map to Keynote operations, such as creating presentations, adding slides, inserting content, and exporting the final product. The server supports a wide range of tools: presentation management (create, open, save, close; set themes; query presentations), slide operations (add, delete, duplicate, move; set layouts; navigate slides), content management (texts, images, shapes, tables, charts; bullet and numbered lists; code blocks and quotes), and export options (screenshots, PDF export, image sequences). Integration with Unsplash is available to fetch and insert images automatically when enabled with an API key.

To use the server, connect with an MCP client configuration that points to the Python script that starts the server. Typical configurations specify the command (python) and the argument to start (start_server.py), along with any environment variables (for example, UNSPLASH_KEY) and the working directory where the server resides. Once connected, you can issue natural language commands like: “Create a new presentation about AI trends,” “Add a slide with the title ‘Machine Learning Basics’,” or “Export the presentation as PDF.”

Prerequisites:\n- macOS 10.14 or later\n- Keynote application installed\n- Python 3.8 or later\n\nInstall steps:\n1. Clone the repository:\nbash\ngit clone https://github.com/easychen/keynote-mcp.git\ncd keynote-mcp\n\n2. Create and activate a Python environment (optional but recommended):\nbash\npython3 -m venv venv\nsource venv/bin/activate # macOS/Linux\n# On Windows: venv\Scripts\activate\n\n3. Install Python dependencies:\nbash\npip install -r requirements.txt\n\n4. Configure environment (optional for Unsplash features):\nbash\ncp env.example .env\n# Edit .env and set UNSPLASH_KEY if you plan to use Unsplash features\n\n5. Start the MCP server:\nbash\npython start_server.py\n\n6. Connect from an MCP client using the provided configuration (as shown in the README examples).

Tips and common issues:\n- macOS permissions: Ensure Terminal and Python have Accessibility and Automation permissions in System Preferences > Security & Privacy > Privacy.\n- If using Unsplash features, supply a valid UNSPLASH_KEY via the environment or .env file.\n- If the server cannot access Keynote, verify AppleScript permissions and that Keynote is installed and accessible.\n- The server expects to run in an environment where Keynote scripting is allowed; running from an IDE may require additional permission prompts.\n- For MCP clients, ensure the working directory points to the keynote-mcp project root where start_server.py resides.\n- If you encounter port or connection issues, check firewall settings and confirm the client is configured with the correct command, args, and environment.\n- Logs are helpful: look for startup messages in the console where start_server.py is executed to verify successful startup and available endpoints.