From 0459fb1d4c8ec3bafd65570b688f9f0635dd55e0 Mon Sep 17 00:00:00 2001 From: Yigit Colakoglu Date: Wed, 31 Dec 2025 13:44:09 -0800 Subject: [PATCH] Rewrite README --- README.md | 273 ++++++++++++------------------------------------------ 1 file changed, 58 insertions(+), 215 deletions(-) diff --git a/README.md b/README.md index 00bb265..6871562 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,56 @@ -# PIM MCP Server +# DAV/IMAP MCP Server -A self-hosted MCP server for managing your email, calendar, and contacts through AI assistants. +A self-hosted MCP server that connects IMAP/SMTP, CalDAV, and CardDAV to MCP-compatible clients. It exposes email, calendar, and contacts tools and can optionally send new email notifications to a Poke webhook. -Connect your existing mail server (IMAP/SMTP) and CalDAV/CardDAV services to any MCP-compatible client. +## Features -## Prerequisites +- Email tools over IMAP/SMTP (list, read, search, send, drafts, flags, unsubscribe) +- Calendar tools over CalDAV (list, create, update, delete) +- Contacts tools over CardDAV (list, create, update, delete) +- Optional email notifications via webhook with IMAP IDLE or polling +- SQLite cache with Alembic migrations +- API key auth for the MCP endpoint -- Docker and Docker Compose (recommended), OR Python 3.12+ -- An email account with IMAP/SMTP access -- (Optional) A CalDAV server for calendars (Nextcloud, Fastmail, Radicale, etc.) -- (Optional) A CardDAV server for contacts +## Quickstart (Docker Compose) -## Setup - -### Option 1: Docker Compose (Recommended) - -1. **Clone the repository** - ```bash - git clone https://github.com/your-repo/pim-mcp-server.git - cd pim-mcp-server - ``` - -2. **Create your environment file** +1. Copy the environment template: ```bash cp .env.example .env ``` -3. **Edit `.env` with your credentials** - ```bash - # Required: Generate an API key - MCP_API_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))") +2. Edit `.env` with your credentials. - # Then edit .env with your mail server details - nano .env - ``` - -4. **Start the server** +3. Start the server: ```bash docker compose up -d ``` -5. **Verify it's running** +4. Verify it is running: ```bash curl http://localhost:8000/mcp ``` -### Option 2: Local Python +## Local Run (Python) -1. **Clone and setup environment** - ```bash - git clone https://github.com/your-repo/pim-mcp-server.git - cd pim-mcp-server - - python -m venv venv - source venv/bin/activate # Windows: venv\Scripts\activate - pip install -r requirements.txt - ``` - -2. **Configure** - ```bash - cp .env.example .env - nano .env # Add your credentials - ``` - -3. **Initialize database** - ```bash - # Create initial migration (first time only) - alembic revision --autogenerate -m "Initial tables" - alembic upgrade head - ``` - -4. **Run** - ```bash - python src/server.py - ``` +```bash +python -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate +pip install -r requirements.txt +cp .env.example .env +# Edit .env +python src/server.py +``` ## Configuration -Edit `.env` with your service credentials. Only configure the services you want to use. +All settings are read from `.env`. Configure only the services you want to enable. -### Minimal Setup (Email Only) +### Minimal email-only setup ```bash -# Server -MCP_API_KEY=your-secret-key-here +MCP_API_KEY=your-secret-key PORT=8000 -# Email IMAP_HOST=imap.example.com IMAP_USERNAME=you@example.com IMAP_PASSWORD=your-password @@ -95,121 +59,67 @@ SMTP_USERNAME=you@example.com SMTP_PASSWORD=your-password SMTP_FROM_EMAIL=you@example.com -# Disable other services ENABLE_CALENDAR=false ENABLE_CONTACTS=false ``` -### Full Setup (Email + Calendar + Contacts) +### Full setup (email + calendar + contacts) ```bash -# Server -MCP_API_KEY=your-secret-key-here +MCP_API_KEY=your-secret-key PORT=8000 -# Email (IMAP/SMTP) IMAP_HOST=imap.example.com IMAP_PORT=993 IMAP_USERNAME=you@example.com IMAP_PASSWORD=your-password +IMAP_USE_SSL=true + SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USERNAME=you@example.com SMTP_PASSWORD=your-password +SMTP_USE_TLS=true SMTP_FROM_EMAIL=you@example.com SMTP_FROM_NAME=Your Name -# Calendar (CalDAV) CALDAV_URL=https://caldav.example.com/dav CALDAV_USERNAME=you@example.com CALDAV_PASSWORD=your-password -# Contacts (CardDAV) CARDDAV_URL=https://carddav.example.com/dav CARDDAV_USERNAME=you@example.com CARDDAV_PASSWORD=your-password ``` -### Provider-Specific Examples +### Email notifications (Poke webhook) -
-Fastmail +Enable notifications to send new-email alerts to Poke. The server will use IMAP IDLE when available and fall back to polling. ```bash -IMAP_HOST=imap.fastmail.com -IMAP_PORT=993 -SMTP_HOST=smtp.fastmail.com -SMTP_PORT=587 -CALDAV_URL=https://caldav.fastmail.com/dav/calendars/user/you@fastmail.com -CARDDAV_URL=https://carddav.fastmail.com/dav/addressbooks/user/you@fastmail.com +ENABLE_EMAIL_NOTIFICATIONS=true +NOTIFICATION_MAILBOXES=INBOX,Updates +NOTIFICATION_POLL_INTERVAL=60 +NOTIFICATION_IDLE_TIMEOUT=1680 + +POKE_WEBHOOK_URL=https://poke.com/api/v1/inbound-sms/webhook +POKE_API_KEY=your-poke-api-key +POKE_WEBHOOK_TIMEOUT=30 +POKE_WEBHOOK_MAX_RETRIES=3 ``` -Use an [app-specific password](https://www.fastmail.help/hc/en-us/articles/360058752854). -
-
-Nextcloud +## MCP Client Setup -```bash -# Use your mail server for IMAP/SMTP -IMAP_HOST=mail.example.com -SMTP_HOST=mail.example.com - -# Nextcloud for CalDAV/CardDAV -CALDAV_URL=https://cloud.example.com/remote.php/dav -CARDDAV_URL=https://cloud.example.com/remote.php/dav -CALDAV_USERNAME=your-nextcloud-user -CARDDAV_USERNAME=your-nextcloud-user -``` -
- -
-Gmail - -```bash -IMAP_HOST=imap.gmail.com -IMAP_PORT=993 -SMTP_HOST=smtp.gmail.com -SMTP_PORT=587 -``` -You must use an [App Password](https://support.google.com/accounts/answer/185833) (not your regular password). - -Note: Gmail's CalDAV/CardDAV requires OAuth2, which is not currently supported. -
- -
-Mailcow - -```bash -IMAP_HOST=mail.example.com -SMTP_HOST=mail.example.com -CALDAV_URL=https://mail.example.com/SOGo/dav -CARDDAV_URL=https://mail.example.com/SOGo/dav -``` -
- -
-Radicale (Self-hosted) - -```bash -CALDAV_URL=https://radicale.example.com/user/ -CARDDAV_URL=https://radicale.example.com/user/ -``` -
- -## Connecting to MCP Clients - -### MCP Inspector (Testing) +### MCP Inspector ```bash npx @modelcontextprotocol/inspector ``` -- Transport: **Streamable HTTP** +- Transport: Streamable HTTP - URL: `http://localhost:8000/mcp` ### Claude Desktop -Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json` on Linux/Mac): - ```json { "mcpServers": { @@ -223,99 +133,32 @@ Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json` ### Poke -Go to [poke.com/settings/connections](https://poke.com/settings/connections) and add your server URL. +Add your MCP endpoint at https://poke.com/settings/connections. ## Available Tools -Once connected, your AI assistant can use these tools: - | Category | Tools | -|----------|-------| -| **Email** | `list_mailboxes`, `list_emails`, `read_email`, `search_emails`, `move_email`, `delete_email`, `send_email` | -| **Calendar** | `list_calendars`, `list_events`, `get_event`, `create_event`, `update_event`, `delete_event` | -| **Contacts** | `list_addressbooks`, `list_contacts`, `get_contact`, `create_contact`, `update_contact`, `delete_contact` | -| **System** | `get_server_info` | +| --- | --- | +| Email | `list_mailboxes`, `list_emails`, `list_drafts`, `read_email`, `search_emails`, `move_email`, `delete_email`, `delete_draft`, `save_draft`, `edit_draft`, `send_email`, `set_email_flags`, `unsubscribe_email` | +| Calendar | `list_calendars`, `list_events`, `get_event`, `create_event`, `update_event`, `delete_event` | +| Contacts | `list_addressbooks`, `list_contacts`, `get_contact`, `create_contact`, `update_contact`, `delete_contact` | +| System | `get_server_info` | -## Database Migrations +## Database and Migrations -The server uses SQLModel with Alembic for database migrations. - -### When you update the code +The server uses SQLite (default: `/data/cache.db`) and Alembic. ```bash -# Pull latest changes -git pull - -# Run any new migrations +alembic revision --autogenerate -m "Describe change" alembic upgrade head - -# Restart -docker compose restart -# or: python src/server.py ``` -### Adding custom fields - -1. Edit `src/database/models.py` -2. Generate migration: `alembic revision --autogenerate -m "Description"` -3. Apply: `alembic upgrade head` - ## Troubleshooting -### Connection refused -- Check the server is running: `docker compose ps` or `curl localhost:8000/mcp` -- Check logs: `docker compose logs -f` - -### Authentication failed (IMAP/SMTP) -- Verify credentials in `.env` -- Many providers require app-specific passwords (Gmail, Fastmail, etc.) -- Check if 2FA is enabled on your account - -### CalDAV/CardDAV not working -- Verify the URL is correct (try opening it in a browser) -- Check if your provider requires a specific URL format -- Some providers need the full path including username - -### Service disabled -If you see "service: disabled (not configured)", check that: -- All required env vars are set (host, username, password) -- `ENABLE_*` is not set to `false` - -### View logs -```bash -# Docker -docker compose logs -f - -# Local -# Logs print to stdout -``` - -## Project Structure - -``` -├── src/ -│ ├── server.py # Entry point -│ ├── config.py # Environment configuration -│ ├── database/ # SQLModel ORM -│ │ ├── models.py # Table definitions -│ │ └── connection.py # Database connection -│ ├── models/ # Pydantic models (API) -│ ├── services/ # Business logic -│ └── tools/ # MCP tool definitions -├── migrations/ # Alembic migrations -├── docker-compose.yml -├── Dockerfile -├── .env.example -└── requirements.txt -``` - -## Security Notes - -- Never commit `.env` files -- Use app-specific passwords where available -- The Docker container runs as non-root -- Consider running behind a reverse proxy with HTTPS for remote access -- The `MCP_API_KEY` is optional but recommended for production +- Connection refused: check `docker compose ps` or `curl http://localhost:8000/mcp` +- Auth errors: confirm `MCP_API_KEY` and client config +- IMAP/SMTP failures: verify credentials and app-specific passwords +- CalDAV/CardDAV failures: confirm base URL and username ## License