Metadata-Version: 2.4
Name: reminders-blade-mcp
Version: 0.2.0
Summary: Apple Reminders MCP Server — lists, reminders, search, due dates, create, complete, update
Author: Piers
License: MIT
License-File: LICENSE
Keywords: apple,eventkit,macos,mcp,reminders
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.12
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# reminders-blade-mcp

Apple Reminders MCP Server — read and manage reminders, lists, due dates, search, create, complete, update, and delete.

## Requirements

- macOS 13 (Ventura) or later
- Python 3.12+
- [uv](https://docs.astral.sh/uv/) package manager
- Reminders permission for your terminal (auto-prompted on first use)

## Quick Start

```bash
# Install
uv sync

# Run
uv run reminders-blade-mcp
```

## Configuration

### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "reminders": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/reminders-blade-mcp", "reminders-blade-mcp"],
      "env": {
        "REMINDERS_WRITE_ENABLED": "false"
      }
    }
  }
}
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `REMINDERS_WRITE_ENABLED` | `false` | Enable create/complete/update/delete operations |
| `REMINDERS_MCP_TRANSPORT` | `stdio` | Transport: `stdio` or `http` |
| `REMINDERS_MCP_HOST` | `127.0.0.1` | HTTP transport bind address |
| `REMINDERS_MCP_PORT` | `8771` | HTTP transport port |

## Tools

### Read (7)

| Tool | Description |
|------|-------------|
| `reminders_info` | System info, access status, list count, write gate |
| `reminders_lists` | All reminder lists with counts |
| `reminders_items` | Reminders from a list (filter: completed/incomplete) |
| `reminders_item` | Single reminder by ID or name |
| `reminders_search` | Search by title text across all lists |
| `reminders_due` | Due/overdue reminders within N days |
| `reminders_stats` | Aggregate stats with per-list breakdown |

### Write (4) — require `REMINDERS_WRITE_ENABLED=true` AND `confirm=true`

| Tool | Description |
|------|-------------|
| `reminders_create` | Create a reminder (title, list, due date, priority, notes) |
| `reminders_complete` | Mark completed or uncompleted |
| `reminders_update` | Update properties (title, due date, priority, notes, flagged) |
| `reminders_delete` | Delete a reminder (cannot be undone) |

## Security

- All user input is escaped to prevent AppleScript injection
- Write operations require both an environment variable gate and per-call confirmation
- Delete operations cannot be undone — double-gated
- Uses `/usr/bin/osascript` (system binary) to avoid TCC permission churn
- 30-second timeout on all AppleScript executions

## Development

```bash
make install-dev   # Install with dev dependencies
make check         # Lint + format + type-check
make test          # Unit tests
make test-cov      # Tests with coverage
make test-e2e      # E2E tests (requires Reminders access)
```

## License

MIT
