apple_reminder_mcp_server

shreyanshjain05/apple_reminder_mcp_server

3.2

If you are the rightful owner of apple_reminder_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Apple Reminders Server provides programmatic access to Apple Reminders using FastMCP and AppleScript integration.

Apple Reminders MCP Server - Documentation

README.md

# Apple Reminders MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Apple Reminders on macOS. This server provides tools to create, read, list, and delete reminders programmatically through AppleScript.

## Features

- āœ… Create reminders with due dates, times, notes, and locations
- šŸ“‹ List all reminder lists
- šŸ” Fetch reminders from specific lists (completed or pending)
- šŸ—‘ļø Delete reminders by name
- šŸ¤– Compatible with Claude Desktop and other MCP clients
- šŸŽ Native macOS integration via AppleScript

## Prerequisites

- macOS (required for AppleScript)
- Python 3.10 or higher
- Apple Reminders app

## Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/apple-reminder-mcp-server.git
cd apple-reminder-mcp-server
  1. Create a virtual environment:
python3 -m venv .venv
source .venv/bin/activate  # On macOS/Linux
  1. Install dependencies:
pip install mcp fastmcp python-dotenv

Configuration

The server uses stdio transport by default, no additional configuration needed.

Usage

Running the Server

python3 server.py

Testing with MCP Inspector

The MCP Inspector is a web-based tool for testing MCP servers. Follow these steps to test your server:

1. Launch MCP Inspector
npx @modelcontextprotocol/inspector stdio "python3 server.py"

This will:

  • Start a proxy server on localhost:6277
  • Open the inspector interface in your browser at http://localhost:6274
  • Display a session token for authentication
2. Configure Connection Settings

When the inspector opens in your browser, configure the connection with these settings:

  • Transport Type: STDIO
  • Command: python3
  • Arguments: /Users/shreyanshjain/apple_reminder_mcp_server/server.py

Note: Replace the path in Arguments with the actual path to your server.py file

3. Connect to the Server

Click "Connect" to establish connection with your MCP server. You should see:

  • Server status change to "Connected"
  • List of available tools in the interface
4. Test the Tools

Example: Testing create_reminder

  1. Select create_reminder from the tools list
  2. Fill in the parameters: 
    {
  "title": "Test Reminder",
  "due_date": "2024-12-25",
  "due_time": "140000",
  "notes": "This is a test reminder",
  "list_name": "Reminder Created using Agent"
}
  3. Click "Execute"
  4. Check the response: 
    {
  "result": "Reminder 'Test Reminder' created successfully in list 'Reminder Created using Agent'. AppleScript Output: "
}

Example: Testing list_reminder_lists

  1. Select list_reminder_lists from the tools list
  2. No parameters needed
  3. Click "Execute"
  4. View your reminder lists in the response

Example: Testing get_reminder

  1. Select get_reminder from the tools list
  2. Fill in parameters: 
    {
  "list_name": "Reminder Created using Agent",
  "completed": false,
  "limit": 10
}
  3. Click "Execute"
  4. View the reminders in the specified list

Integration with Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "apple-reminders": {
      "command": "python3",
      "args": ["/path/to/your/apple_reminder_mcp_server/server.py"]
    }
  }
}

Available Tools

1. create_reminder

Creates a new reminder in Apple Reminders.

Parameters:

  • title (required): The title of the reminder
  • due_date (required): Due date in YYYY-MM-DD format
  • due_time (optional): Time in HHMMSS format (default: 090000 for 9 AM)
  • notes (optional): Additional notes/body text
  • list_name (optional): Target list name (default: "Reminder Created using Agent")
  • location (optional): Location for location-based reminders

Example Request:

{
  "title": "Team Meeting",
  "due_date": "2024-12-25",
  "due_time": "140000",
  "notes": "Discuss Q1 goals",
  "list_name": "Work"
}

Example Response:

{
  "result": "Reminder 'Team Meeting' created successfully in list 'Work'. AppleScript Output: "
}

2. get_reminder

Fetches reminders from a specific list.

Parameters:

  • list_name (required): Name of the reminder list
  • completed (optional): Whether to fetch completed reminders (default: false)
  • limit (optional): Maximum number of reminders to return (default: 20)

Example Response:

[
  {
    "name": "Team Meeting",
    "body": "Discuss Q1 goals",
    "due_date": "Wednesday, December 25, 2024 at 2:00:00 PM",
    "completed": false
  }
]

3. list_reminder_lists

Returns all available reminder lists.

Parameters: None

Example Response:

[
  "Reminders",
  "Work",
  "Personal",
  "Shopping",
  "Reminder Created using Agent"
]

4. delete_reminder

Deletes a reminder by name.

Parameters:

  • name (required): The exact name of the reminder to delete
  • list_name (optional): Specific list to search in (searches all lists if not provided)

Example Response:

{
  "result": "Deleted 1 reminder(s) named 'Team Meeting' from list 'Work'"
}

Output Schema

All tools return responses following this schema:

{
  "type": "object",
  "properties": {
    "result": {
      "title": "Result",
      "type": "string"
    }
  },
  "required": ["result"],
  "title": "ToolOutput"
}

Project Structure

apple_reminder_mcp_server/
ā”œā”€ā”€ server.py           # Main MCP server implementation
ā”œā”€ā”€ requirements.txt    # Python dependencies
ā”œā”€ā”€ .gitignore         # Git ignore file
ā””ā”€ā”€ README.md          # This file

Troubleshooting

Common Issues

  1. "spawn python3 ENOENT" error in MCP Inspector

    • Use separate fields for command and arguments
    • Command: python3
    • Arguments: /full/path/to/server.py

  2. "No reminder list found" error

    • Make sure the list name exactly matches (case-sensitive)
    • Use list_reminder_lists to see available lists

  3. Permission errors with AppleScript

    • Grant Terminal/IDE permission to control Reminders in System Preferences > Security & Privacy > Automation

  4. MCP Inspector connection issues

    • Ensure the path in Arguments is absolute, not relative
    • Check that Python 3 is in your system PATH
    • Try using the full Python path: /usr/bin/python3 or /opt/homebrew/bin/python3

Debug Mode

To enable debug logging, modify the logging level in server.py:

logging.basicConfig(level=logging.DEBUG)

Verifying Server Operation

You can verify the server is working by checking the terminal output:

INFO:root:Starting MCP server with stdio transport...

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Support

For issues and questions:

  • Open an issue on GitHub
  • Check existing issues for solutions
  • Ensure you're running on macOS with proper permissions