Skip to content

README.md

Latest commit

 

History

History
128 lines (99 loc) · 3.77 KB

README.md

File metadata and controls

128 lines (99 loc) · 3.77 KB

mcp-servers

A collection of Python MCP servers that give AI assistants (Cursor, Claude Desktop, etc.) access to personal productivity tools.

Servers

Server Access Tools
mcp-calendar Read/write list_calendars, list_events, create_event, update_event, delete_event, check_free_busy
mcp-gmail Read-only gmail_list_labels, gmail_list_messages, gmail_get_message

mcp-calendar

Full read/write access to calendars across Google Calendar, Microsoft Outlook / Microsoft 365, Apple iCloud, and any generic CalDAV server (Nextcloud, Fastmail, Radicale, ?). Only providers with credentials in .env are activated ? the rest are silently skipped.

Tool Description
list_calendars List all available calendars for a provider
list_events Search and filter events by date range and keyword
create_event Create a new event with attendees, location, recurrence
update_event Partially update an existing event
delete_event Permanently delete an event
check_free_busy Check free/busy availability in a time window

? See mcp-calendar/README.md for setup and configuration.

mcp-gmail

Read-only access to Gmail via Google OAuth. Cannot send, delete, or modify mail ? only gmail.readonly scope is requested.

Tool Description
gmail_list_labels List all Gmail labels (INBOX, SENT, DRAFT, TRASH, SPAM, custom labels, ?)
gmail_list_messages List messages filtered by label, search query, and pagination
gmail_get_message Fetch a single message ? full headers, plain text, and HTML body

? See mcp-gmail/README.md for setup and configuration.

Prerequisites

  • Python 3.10+
  • uv

Each server has its own virtual environment. Install them independently:

cd mcp-calendar && uv sync
cd mcp-gmail    && uv sync

Connecting to Cursor

Add both servers to your Cursor MCP config (via Cursor ? Settings ? MCP):

{
  "mcpServers": {
    "mcp-calendar": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Users/Ryzen/Projects/mcp-servers/mcp-calendar",
        "mcp-calendar"
      ]
    },
    "mcp-gmail": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Users/Ryzen/Projects/mcp-servers/mcp-gmail",
        "mcp-gmail"
      ]
    }
  }
}

Connecting to Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "mcp-calendar": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Users/Ryzen/Projects/mcp-servers/mcp-calendar",
        "mcp-calendar"
      ]
    },
    "mcp-gmail": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/Users/Ryzen/Projects/mcp-servers/mcp-gmail",
        "mcp-gmail"
      ]
    }
  }
}

Shared Google OAuth Client

Both mcp-calendar (Google Calendar) and mcp-gmail can share the same Google Cloud OAuth 2.0 client ID and secret. They use separate token files so each is scoped independently:

mcp-calendar/tokens/google_token.json   # scope: calendar
mcp-gmail/tokens/gmail_token.json       # scope: gmail.readonly

Security

  • Never commit .env files or tokens/ directories ? both are in each server's .gitignore.
  • mcp-gmail only requests gmail.readonly and cannot send, delete, or modify mail.
  • OAuth tokens are stored locally and refreshed automatically.