Metadata-Version: 2.4
Name: meeting-scheduler-mcp
Version: 1.1.8
Summary: MCP server for cross-organisation meeting scheduling via Google and Microsoft calendars
Author: Shathish Ravindran
License-Expression: MIT
Project-URL: Homepage, https://github.com/shathish/meeting-scheduler-mcp
Project-URL: Bug Tracker, https://github.com/shathish/meeting-scheduler-mcp/issues
Keywords: mcp,calendar,scheduling,google-calendar,outlook,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Communications
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: google-api-python-client>=2.100.0
Requires-Dist: google-auth>=2.23.0
Requires-Dist: google-auth-oauthlib>=1.1.0
Requires-Dist: msal>=1.24.0
Requires-Dist: msal-extensions>=1.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pytz>=2023.3
Requires-Dist: pywin32>=306; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# meeting-scheduler-mcp

An MCP server that schedules meetings across organisations by querying free/busy calendars from Google and Microsoft accounts — without exposing anyone's calendar data to the other party.

Works with Claude Desktop, Cursor, and any MCP-compatible client.

---

## How it works

You configure one **primary** account (the calendar where events are created and invites sent) and one or more **shadow** accounts (read-only access to query free/busy within another org's tenant).

Claude uses the MCP tools to:
1. Find slots where everyone is free
2. Book the meeting from your primary calendar
3. Reschedule or cancel if plans change

---

## Prerequisites

### Google account

1. Go to [Google Cloud Console → APIs & Services → Credentials](https://console.cloud.google.com/apis/credentials)
2. Create a project (or use an existing one)
3. Enable the **Google Calendar API**
4. Create an **OAuth client ID** — application type: **Desktop app**
5. Download the client ID and client secret

### Microsoft / Outlook account

1. Go to [Azure Portal → App registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps)
2. Register a new application — supported account types: **Accounts in any organizational directory and personal Microsoft accounts**
3. Under **Authentication**, add a **Mobile and desktop application** redirect URI: `http://localhost`
4. Note the **Application (client) ID** — no client secret needed for delegated auth

---

## Installation

### Recommended — zero install via uvx

```bash
uvx meeting-scheduler-mcp setup
```

This runs the setup wizard without permanently installing anything. Once configured, Claude Desktop launches the server automatically using the same `uvx` command.

### Alternative — pip

```bash
pip install meeting-scheduler-mcp
meeting-scheduler setup
```

---

## Setup wizard

Run the wizard once to configure your accounts and authorise them:

```
$ uvx meeting-scheduler-mcp setup

Meeting Scheduler — Setup Wizard
==================================================

This wizard will:
  1. Collect your calendar account details
  2. Write ~/.config/meeting-scheduler/config.toml
  3. Open a browser to authorise each account
```

The wizard asks for each account's email, provider (google/microsoft), and OAuth credentials, then opens a browser window for each one.

After setup, re-authorise a single account at any time:

```bash
uvx meeting-scheduler-mcp auth you@company.com
```

Check that all accounts are connected:

```bash
uvx meeting-scheduler-mcp status
```

---

## Claude Desktop configuration

Add this to your Claude Desktop MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "meeting-scheduler": {
      "command": "uvx",
      "args": ["meeting-scheduler-mcp"]
    }
  }
}
```

Restart Claude Desktop. You should see the meeting-scheduler tools available.

---

## Configuration file

The wizard writes `~/.config/meeting-scheduler/config.toml`. You can also edit it directly:

```toml
[[accounts]]
org           = "Acme Corp"
email         = "you@acme.com"
provider      = "google"
is_primary    = true
client_id     = "YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com"
client_secret = "YOUR_GOOGLE_CLIENT_SECRET"

[[accounts]]
org        = "Partner Inc"
email      = "you@partner.com"
provider   = "microsoft"
is_primary = false
client_id  = "YOUR_AZURE_APP_CLIENT_ID"

[rules]
default_duration_minutes      = 30
buffer_before_minutes         = 0
buffer_after_minutes          = 15
default_working_hours_start   = "09:00"
default_working_hours_end     = "17:00"
working_days                  = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
advance_notice_hours          = 24
max_days_ahead                = 30
slot_limit                    = 10
```

Set `MEETING_SCHEDULER_CONFIG` to use a different path:

```bash
export MEETING_SCHEDULER_CONFIG=/path/to/my-config.toml
```

---

## Available MCP tools

| Tool | Description |
|------|-------------|
| `find_available_slots` | Find free slots for all participants within a time window |
| `book_meeting` | Create a calendar event and send invites |
| `reschedule_meeting` | Move an existing event to a new time |
| `cancel_meeting` | Delete an event |
| `list_accounts` | Show configured accounts and connection status |
| `health_check` | Verify all accounts can authenticate |

---

## Token security

Credentials are stored locally and never sent anywhere except the respective calendar provider:

- **Google** — refresh token is AES-256-GCM encrypted; the encryption key lives in an ACL-locked macOS Keychain item (or DPAPI-protected blob on Windows) that only this process can read
- **Microsoft** — token cache managed by [msal-extensions](https://github.com/AzureAD/microsoft-authentication-extensions-for-python), stored in macOS Keychain (ACL-locked) or a DPAPI-encrypted file on Windows

---

## Development

```bash
git clone https://github.com/shathish/meeting-scheduler-mcp
cd meeting-scheduler-mcp
pip install -e ".[dev]"
pytest tests/
```

To run the server locally against Claude Desktop, point the config at the repo:

```json
{
  "mcpServers": {
    "meeting-scheduler": {
      "command": "python3",
      "args": ["/path/to/meeting-scheduler-mcp/mcp_server.py"]
    }
  }
}
```

---

## License

MIT — see [LICENSE](LICENSE)
