mcp -agenda

This MCP server provides a Python-based integration for controlling the Agenda app on macOS via Claude AI using Agenda’s x-callback-url scheme. It exposes capabilities to create notes, create and manage projects, and open existing notes directly from Claude. The server is installed and run using the uv tool (a modern Python package installer and resolver). Once running, Claude can invoke the server’s endpoints to issue x-callback-url actions like create-note, open-note, and create-project, enabling AI-generated content creation and organization inside Agenda. To use it with Claude, configure the Claude desktop to point at the server (as shown in the configuration example) so Claude can send requests to the MCP server and perform actions in Agenda from your AI conversations.

Prerequisites:

• macOS
• Python 3.7+
• Agenda app installed
• uv (see installation steps)

Step-by-step:

1. Clone the repository: git clone https://github.com/yourusername/mcp-server-agenda.git cd mcp-server-agenda

2. Install uv (Python package manager) if you don’t have it: pip install uv

3. Create and/or install the project in development mode (requires a pyproject.toml as shown in the project setup): uv pip install -e .

4. Run the MCP server (example using uv as shown in Claude configuration): uv run mcp-server-agenda

5. Optional: configure Claude to connect to the server by adding the Claude Desktop config (see the Claude configuration snippet in the README).

Tips and notes:

• Ensure the Agenda app is installed and accessible on macOS. The server relies on Agenda’s x-callback-url scheme for actions like create-note, open-note, and create-project.
• The configuration example uses a file path placeholder; replace /Users/your.username with your actual home directory.
• If you change the project directory, update the Claude config accordingly to point to the new --directory path.
• The pyproject.toml is required for uv to build and install the project; ensure it includes your dependencies and build-system configuration.
• For debugging, verify that Agenda accepts x-callback-url requests and that the macOS security settings allow the server to trigger Agenda actions.
• If you encounter issues with uv, check that Python 3.7+ is active in your environment and that the development directory contains the mcp-server-agenda package entry points.