Skip to content

Readme.md

Latest commit

 

History

History
230 lines (170 loc) · 7.07 KB

Readme.md

File metadata and controls

230 lines (170 loc) · 7.07 KB
Raw

Personal Ops MCP Server

A local-first MCP server that turns your everyday digital life into AI-accessible tools. Connect it to Claude Desktop and ask things like "What do I need to know today?" — it reads your Gmail, Google Calendar, Google Drive, local notes, and tasks, then answers in plain English.

Python MCP Claude

How it works

You (in Claude Desktop)
    → "Summarize my unread emails"
        → Claude calls list_unread() on your local MCP server
            → server hits Gmail API → returns structured data
                → Claude answers in plain English

No web app, no third-party middleman. The server runs on your machine and your credentials never leave it.

Available tools

Tool What it does
daily_briefing Unread emails + today's events + pending tasks in one call
list_unread List unread emails with sender, subject, snippet
search_emails Gmail search syntax e.g. from:boss subject:report
read_email Full body of an email by message ID
list_calendar_events Upcoming events (today, this week, etc.)
create_calendar_event Add an event to your Google Calendar
list_todos List pending tasks (stored locally in SQLite)
create_todo Create a task with optional due date
complete_todo Mark a task done by ID
search_notes Search local notes by keyword
get_note Get full note content by ID
create_note Save a note with title and body
find_file Search Google Drive by name or content
recent_files List most recently modified Drive files

Setup

1. Clone and install

git clone https://github.com/hatimanees/ops_mcp
cd personal-ops-mcp-server

python -m venv venv

# Windows
venv\Scripts\activate

# Mac / Linux
source venv/bin/activate

pip install -r requirements.txt

Copy the env file:

cp .env.example .env

2. Get Google credentials

You need a credentials.json from Google Cloud Console. Follow these steps exactly:

a) Create a project

b) Enable APIs

  • Go to APIs & Services → Library
  • Enable these three:
    • Gmail API
    • Google Calendar API
    • Google Drive API

c) Configure OAuth consent screen

  • Go to APIs & Services → OAuth consent screen
  • Choose External
  • Fill in App name (anything) and your email
  • Under Scopes: add Gmail, Calendar, Drive scopes
  • Under Test users: add your own Gmail address ← do not skip this or you will get 403 access_denied
  • Save

d) Create OAuth credentials

  • Go to APIs & Services → Credentials
  • Click + Create Credentials → OAuth client ID
  • Application type: Desktop app ← must be Desktop, not Web
  • Download the JSON file
  • Rename it to credentials.json and place it in the project root

The file should start with {"installed": — if it starts with {"web": you created the wrong type, repeat step d.

3. Run one-time Google auth

This opens a browser window for you to sign in and approve access. Only needed once — saves a token.json that is reused automatically.

python auth_setup.py

Sign in with the Google account you added as a test user. After approval, token.json is saved and the browser can be closed.

If you see Error 403: access_denied — go back to the OAuth consent screen and make sure your email is listed under Test users.

4. Connect Claude Desktop

Find your Claude Desktop config file:

OS Path
Windows (Store) C:\Users\<you>\AppData\Local\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json
Windows (direct install) C:\Users\<you>\AppData\Roaming\Claude\claude_desktop_config.json
Mac ~/Library/Application Support/Claude/claude_desktop_config.json

Add this to the file (use the full Python path, not just python):

Windows:

{
  "mcpServers": {
    "personal-ops": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python313\\python.exe",
      "args": ["C:\\path\\to\\ops_mcp\\mcp_server.py"]
    }
  }
}

Mac / Linux:

{
  "mcpServers": {
    "personal-ops": {
      "command": "/usr/bin/python3",
      "args": ["/path/to/ops_mcp/mcp_server.py"]
    }
  }
}

Use the full path to python.exe — Claude Desktop may not inherit your terminal PATH and will silently fail if python is not found.

5. Restart Claude Desktop

Fully quit Claude Desktop (right-click tray icon → Quit) and reopen it.

Do NOT run python mcp_server.py manually. Claude Desktop launches it automatically via stdio. If you run it in a terminal it will just hang silently waiting for MCP input — that is normal stdio behavior.

Try it

"What do I need to know today?"         → daily_briefing
"What's on my calendar tomorrow?"       → list_calendar_events
"Find the project proposal I wrote"     → find_file
"Any unread emails from Ahmed?"         → search_emails
"Create a task: follow up on Friday"    → create_todo

Project structure

ops_mcp/
├── mcp_server.py          ← entry point, all tools registered here
├── auth_setup.py          ← one-time Google OAuth flow
├── config.py              ← reads .env settings
├── .env                   ← your local config (gitignored)
├── .env.example           ← template
├── credentials.json       ← Google OAuth client (gitignored)
├── token.json             ← saved after auth_setup.py (gitignored)
├── requirements.txt
├── tools/                 ← (unused stubs, logic lives in mcp_server.py)
├── integrations/
│   ├── auth.py            ← OAuth token load/refresh
│   ├── gmail.py           ← Gmail API calls
│   ├── google_calendar.py ← Calendar API calls
│   ├── drive.py           ← Drive API calls
│   └── local_db.py        ← SQLite for notes and tasks
└── data/
    └── notes.db           ← auto-created on first run

Troubleshooting

Problem Fix
403 access_denied on Google sign-in Add your email to Test users in OAuth consent screen
Hammer icon not showing in Claude Desktop Check config JSON is valid, use full python path, fully restart Claude Desktop
{"web": in credentials.json Wrong OAuth type — recreate as Desktop app
Server hangs when run manually Normal — it runs in stdio mode, only works when launched by Claude Desktop
Token expired Delete token.json and run python auth_setup.py again

Stack

Component Choice
Language Python 3.10+
Protocol Model Context Protocol (MCP) via FastMCP
Client Claude Desktop
Storage SQLite (notes + tasks), Google APIs (email/calendar/drive)
Auth Google OAuth 2.0 (Desktop app flow)

License

MIT