mcp-home

Self-hosted MCP 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

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

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