proactive-mcp — Claude Code MCP server: Gmail and Calendar situations
Watches Gmail and Google Calendar through read-only scopes and hands your agent structured situations: a reply deadline, overlapping meetings, a personal date.
claude mcp add proactive-mcp -- uvx proactive-mcpWhat proactive-mcp does
A background watcher pulls mail and calendar events, and a rules engine compares those snapshots with memory stored in a local SQLite file. You do not get an alert for every new message. Instead the server produces a short list of situations, each with a title, a reason it matters now, bounded evidence, priority and expiry.
Your agent asks for them by calling proactive_check, then delivers whatever it finds over its own channel. The daemon never runs a host or a model, so scheduling belongs to the host. Text pulled from mail and calendar stays marked as untrusted.
Setup wants uv, Git and your own Google Cloud Desktop OAuth client JSON. The PyPI 0.2.0 package predates the setup wizard, so the README routes every command through uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268; plain uvx proactive-mcp still resolves to the older release. Once Google consent is granted, register the watcher with proactive-mcp service install or run the daemon by hand.
What it helps with
- catch a message that needs a reply before the deadline passes
- spot two accepted calendar events that overlap
- remember a personal date saved in local memory
- let the agent open a conversation instead of waiting for a prompt
- keep situation data on the machine in SQLite
Example prompts for the agent
- Run
proactive_checkand tell me if anything needs a reply today. - Call
proactive_checkand list the high-priority situations. - Check
proactive_checkfor calendar conflicts this week.
How to install proactive-mcp
Platform CLI
claude mcp add proactive-mcp -- uvx proactive-mcpuvx runs the command named after the package; if the README names another one, use uvx --from proactive-mcp <command>
Platform CLI
codex mcp add proactive-mcp -- uvx proactive-mcpuvx runs the command named after the package; if the README names another one, use uvx --from proactive-mcp <command>
Config file
{
"mcpServers": {
"proactive-mcp": {
"command": "uvx",
"args": [
"proactive-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from proactive-mcp <command>
Config file
{
"servers": {
"proactive-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"proactive-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from proactive-mcp <command>
Platform CLI
gemini mcp add proactive-mcp uvx proactive-mcpuvx runs the command named after the package; if the README names another one, use uvx --from proactive-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about proactive-mcp
How do I install proactive-mcp in Claude Code?
Register it with claude mcp add proactive-mcp -- uvx proactive-mcp. For the watcher, memory and service setup, run the README setup step with the uvx --from git+https://github.com/madrobotnet/proactive-mcp@7cd0f03243027df464084c3957f03d3c42169268 prefix first.
What does proactive-mcp do?
It turns read-only Gmail and Google Calendar data plus locally saved memory into structured situations: a reply deadline, a calendar conflict, an approaching personal occasion. The agent fetches them with proactive_check and picks its own delivery channel.
What has to be ready before setup?
uv, Git, and a Google Cloud Desktop OAuth client JSON of your own, plus consent for read-only Gmail and Calendar access. Without the client file the wizard cannot complete authorization.
