# mcp-home

Self-hosted [MCP](https://modelcontextprotocol.io) servers for Claude. Gives Claude access to your email, calendar, contacts, files, and notes — all running on your own hardware, behind OAuth.

## Services & Tools

- **Mail** — `list_accounts`, `list_folders`, `search_mail` (full text), `read_mail` (lists attachments), `read_attachment` (image/PDF/text), `create_draft`
- **Calendar + Tasks** — `list_calendars`, `get_events`, `search_events`, `list_task_lists`, `get_tasks`, `create_event` (travel time + geocoding + reminders), `create_task`
- **Contacts** — `search_contacts`, `get_contact` (with photo), `create_contact`, `set_contact_photo`
- **Files** — `list_files`, `read_file` (image/document/text), `file_info`, `search_files`, `write_file`, `create_folder`, `delete_file`, `move_file`
- **Notes** — `list_notebooks`, `list_notes`, `search_notes`, `read_note`, `create_note`, `list_note_resources`, `read_resource` (attachments)

## Setup

```bash
python3 -m venv venv
venv/bin/pip install mcp[cli] httpx vobject python-dateutil pytest
cp tokens.json.example tokens.json      # set OAuth client secrets
cp config.json.example config.json      # set backend credentials
```

Notes needs joplin-cli sync clients exposing the Data API (see `/opt/joplin-mcp/`).

## Usage with claude.ai

Settings → Integrations → Custom MCP Server:

- **URL**: `https://<service>.mcp.your-domain/mcp` (mail, calendar, contacts, files, notes)
- **OAuth Client ID**: your username (e.g. `stefan`)
- **OAuth Client Secret**: from `tokens.json`

claude.ai runs the OAuth Authorization Code + PKCE flow automatically.

## Tests

```bash
venv/bin/python -m pytest tests/test_all.py -v
```

54 integration tests (OAuth, all tools, CRUD in isolated test collections). Run daily via `mcp-tests.timer`.

## License

MIT