Pim
FreeNot checkedOne login for your agent’s mail and calendar: an MCP server for IMAP and CalDAV
About
One login for your agent’s mail and calendar: an MCP server for IMAP and CalDAV
README
PIM is short for personal information manager, the kind of app that keeps your mail and calendar together. pim-mcp lets an AI agent read your mail and manage your calendar on your own servers, with one login. The agent can find the meeting in an email and put it in your calendar in one step, with recurrence and time zones intact. It's built on the assumption that agents make mistakes and that invites come from strangers: your password stays in your keychain, your mail can't be changed, and a stale write can't overwrite an edit you just made on your phone.
- One login per account. Enter your email address and password, and it finds your IMAP and CalDAV servers itself. Add more than one account if you like: the first is the default, and the agent can name another.
- Password in your keychain. Never in a config file, never in logs, and never sent anywhere until you've confirmed the servers.
- Email to calendar. It previews what an invite would do, then imports it. Importing twice changes nothing, and a newer version of an invite updates the event.
- Encrypted, verified connections. Certificates are always checked, and there's no switch to turn that off.
- Safe writes. Every change is conditional on the version the agent read. If the event changed since, the write fails and your copy stays.
- Read-only mode.
--read-onlyremoves every tool that can change something, so the agent can't call them at all. - Mail can't be changed. No tool sends, moves or deletes mail, and reading leaves it unread.
- Self-hosted first. Integration tests run against Dovecot, Radicale, Baïkal and Nextcloud, with 38 calendar test files.
- One binary. Written in Go, about 16 MB, with time zone data built in.
You: Add the meeting from Jan's last email to my calendar.
Agent: mail_search → "Project kickoff", from Jan, has a calendar invite
calendar_preview_import → create "Kickoff, phase 1", 15 Jan 09:00–10:00,
weekly, overlaps nothing
"This adds a weekly meeting from 15 January. Shall I?"
You: Yes.
Agent: calendar_import_from_email → created
Early days. Reading mail and calendars has been tried on one real provider. Creating, changing and importing events have only run against the test servers above, so start with
--read-only.
Getting started
You need an MCP client such as Claude Code.
1. Install it with Homebrew:
brew install --cask robinvdvleuten/tap/pim-mcp
Each release also has archives for macOS, Linux and Windows, and .deb, .rpm and .apk packages. To run it in Docker instead, see Docker.
2. Add your account. It shows the servers it found and asks before your password goes there. If your provider has app passwords, use one. To add another account later, run the same command with its address. The first account you add is the default.
pim-mcp account add --email [email protected]
3. Check that it can log in:
pim-mcp account test
imap: ok
caldav: ok
4. Connect your MCP client, read-only to begin with. For Claude Code:
claude mcp add pim -- "$(command -v pim-mcp)" serve --read-only
5. Ask your agent something like "What's on my calendar next week?"
When you're happy with what it does, add the server again without --read-only to allow changes.
Docker
The image is ghcr.io/robinvdvleuten/pim-mcp. A container has no keychain, so the password comes from PIM_MCP_PASSWORD, which limits you to one account. The account settings live in a folder on your machine that each container mounts.
Put the password in your shell without it going into your history:
read -rs PIM_MCP_PASSWORD && export PIM_MCP_PASSWORD
Add the account and check it:
docker run -it --rm -e PIM_MCP_PASSWORD -v "$HOME/.config/pim-mcp:/home/nonroot/.config/pim-mcp" ghcr.io/robinvdvleuten/pim-mcp account add --email [email protected]
docker run --rm -e PIM_MCP_PASSWORD -v "$HOME/.config/pim-mcp:/home/nonroot/.config/pim-mcp" ghcr.io/robinvdvleuten/pim-mcp account test
Connect Claude Code. This stores the password in Claude Code's own settings:
claude mcp add pim -e PIM_MCP_PASSWORD="$PIM_MCP_PASSWORD" -- docker run -i --rm -e PIM_MCP_PASSWORD -v "$HOME/.config/pim-mcp:/home/nonroot/.config/pim-mcp" ghcr.io/robinvdvleuten/pim-mcp serve --read-only
The container runs as user 65532. On Linux without Docker Desktop, that user needs to own the folder: sudo chown 65532 ~/.config/pim-mcp.
From source
With Go, which downloads the exact version this project needs by itself:
go install github.com/robinvdvleuten/pim-mcp/cmd/pim-mcp@latest
Tools
| Tool | What it does | Read-only mode |
|---|---|---|
account_info |
Shows an account, its servers and your time zone, and lists your accounts | ✓ |
mail_list_folders |
Lists mail folders and their roles | ✓ |
mail_search |
Searches a folder by sender, subject, text, date, or whether it holds an invite | ✓ |
mail_get |
Reads a message: headers, text (HTML is turned into text) and a list of its parts, or the text of one part | ✓ |
calendar_list_calendars |
Lists calendars | ✓ |
calendar_list_events |
Lists events in a range, with recurring events expanded | ✓ |
calendar_free_busy |
Finds when you're busy | ✓ |
calendar_preview_import |
Shows what importing an invite would do, and writes nothing | ✓ |
calendar_create_event |
Creates an event, optionally recurring from an RRULE | |
calendar_update_event |
Changes an event, or one occurrence of a recurring one | |
calendar_delete_event |
Deletes an event, or one occurrence of a recurring one | |
calendar_import_from_email |
Adds, updates or cancels an event from an invite |
Mail is always read-only: no tool sends, moves, flags or deletes a message, and reading leaves it unread.
Every tool takes an optional account, the email address of the account to use. Leave it out and the default account is used. An id from mail_search, calendar_list_calendars or calendar_list_events belongs to the account that returned it, so the agent passes the same account again.
Security
Your password
- It's stored in the OS keychain. The config file holds only endpoints and usernames, with owner-only permissions (
0600in a0700directory). - There's no
--passwordflag, so it can't end up in your shell history or process list. A CalDAV URL containing a password is refused. - During setup, nothing is sent until you've seen the servers it found and said yes, because those answers come from DNS and websites.
- Debug logs record which tool ran and how long it took, never arguments or results. A test runs the real binary and checks the logs for the password and message content.
Your connections
- IMAP uses TLS or required STARTTLS, and CalDAV uses HTTPS. Certificates are always verified.
- Unencrypted connections are only allowed to this machine, for testing.
- A redirect to plain HTTP is refused, as is a calendar server that points to another host, so your password can't be led elsewhere.
Your data
- Folders are opened read-only and messages read without marking them seen, so mail can't change even by accident.
- Every calendar write names the version it was based on. A test edits an event from a second client mid-way and checks that the first write fails and nothing is lost.
- Asking to delete one occurrence can't delete a whole series: scope and occurrence have to agree, or the call fails.
- Any new tool counts as a write unless it says otherwise, so read-only mode can't miss one.
What strangers send you
Invites and mail are treated as hostile input:
- Text is escaped before it's stored, so a summary or description can't smuggle extra properties into an event.
- Recurrence rules, time zone definitions, message sizes and server responses all have limits, to keep a bad invite from tying up the machine.
- Tool descriptions tell the agent to treat mail and invites as information, not instructions.
What it can't protect you from
Prompt injection is still possible. An email can try to talk your agent into something, and a warning in a tool description is no guarantee. An agent with these tools can read all your mail, and, unless read-only, change or delete calendar events. Your defences are
--read-only,--tools, and an MCP client that asks before calling tools that write.
- Anything your agent reads goes to your AI provider, and to any other tools the agent has.
- The password opens your whole account. Use an app password if your provider has them.
PIM_MCP_PASSWORDis visible to anything that can read the process's environment. Use the keychain where you can. It is one password, so it only works with a single account: with several, pim-mcp refuses to use it rather than send it to every account's servers.- No independent security audit has been done.
Configuration
Finding servers. account add tries built-in settings for mailbox.org, Fastmail and Posteo, then DNS, then the well-known locations providers publish. To skip this, name the servers yourself:
pim-mcp account add --email [email protected] --username you --imap mail.example.org:993 --caldav https://dav.example.org/
One lookup, Mozilla's ISPDB, tells Mozilla your email domain. --no-ispdb turns it off. Your full address is never sent during discovery.
Choosing tools. serve --tools mail_search,mail_get offers only those tools. Read-only mode still applies on top.
Environment variables:
| Variable | Effect |
|---|---|
PIM_MCP_PASSWORD |
Uses this password instead of the keychain, for Docker and CI. Only works with a single account; with several it is an error |
PIM_MCP_READ_ONLY=1 |
Same as --read-only |
PIM_MCP_DEBUG=1 |
Logs each request to stderr: the tool and how long it took, never its arguments or results |
Other commands are account show, which lists the accounts and marks the default, account test [--email ADDRESS], account remove [--email ADDRESS] (--email is needed when you have several) and account default --email ADDRESS, which makes an account the default.
Limits
- Ids belong to one account. The agent has to pass the same
accountthat gave it a message, calendar or event id. A wrong pairing is usually refused, but that is not guaranteed, so it can read or list the wrong account. - No replying to invites. Importing adds the event to your calendar and tells nobody. On a server that handles scheduling itself, changing an event you organize can make that server notify its attendees.
- No Google or Microsoft sign-in. Only servers that accept a username and password work.
- Recurring events can be created, from an RRULE such as
FREQ=WEEKLY;BYDAY=MO, and a timed one needs a time zone. Editing covers a whole series or a single occurrence, not "this and following", and a series' rule can't be changed after it is created. - Searches that have to read messages, such as for invites, stop after 2000 and say that there may be more.
- Ranges and sizes. Event listings cover at most 366 days and 1000 occurrences. Messages over 25 MiB aren't read.
Development
Install mise, which fetches the pinned Go, linter and Vale, then set up the commit hook:
mise install && mise run setup
Check a change: formatting, unit tests, lint and known vulnerabilities.
mise run check
Integration tests need Docker. This starts fresh test servers, runs the suite and removes them:
mise run integration
Set PIM_MCP_TEST_NEXTCLOUD=1 to include Nextcloud, and PIM_MCP_TEST_STACK=1 to run a second stack beside the first on other ports.
The reasoning behind the design is in DESIGN.md, and what a review looks for is in CODING_STANDARDS.md.
License
MIT © Robin van der Vleuten. See LICENSE for more information.
Installing Pim
This server has no published package — it is built from source. Open the repository and follow its README.
▸ github.com/robinvdvleuten/pim-mcpFAQ
Is Pim MCP free?
Yes, Pim MCP is free — one-click install via Unyly at no cost.
Does Pim need an API key?
No, Pim runs without API keys or environment variables.
Is Pim hosted or self-hosted?
Self-hosted: the server runs locally on your machine via the install command above.
How do I install Pim in Claude Desktop, Claude Code or Cursor?
Open Pim on unyly.org, pick your client tab (Claude Desktop, Claude Code, Cursor) and press Install — the config is generated automatically, no JSON editing.
Related MCPs
Gmail
Read, send and search emails from Claude
by GoogleSlack
Send, search and summarize Slack messages
by SlackRunbear
No-code MCP client for team chat platforms, such as Slack, Microsoft Teams, and Discord.
Discord Server
A community discord server dedicated to MCP by [Frank Fiegel](https://github.com/punkpeye)
Klavis AI
Open Source MCP Infra. Hosted MCP servers and MCP clients on Slack and Discord.
Work90210/APIFold
Turn any REST API into a hosted MCP server, with ready-made public servers for GitHub, Stripe, Slack, OpenAI, Notion and more.
by Work90210arikusi/deepseek-mcp-server
DeepSeek AI chat and reasoning with multi-turn sessions, function calling, thinking mode and cost tracking.
by arikusihashgraph-online/hashnet-mcp-js
Discover, register and chat with AI agents on the Hashgraph network via the Registry Broker.
by hashgraph-onlineprofullstack/mcp-server
Developer utilities: SEO optimization, document conversion, domain lookup, email validation, QR codes, weather data, social media posting and security scanning.
by profullstackWayStation-ai/mcp
Connect MCP hosts to apps such as Notion, Slack, Monday and Airtable.
by waystation-aiCompare Pim with
Not sure what to pick?
Find your stack in 60 seconds
Author?
Embed badge for your README
Browse similar
All communication MCPs
