outlook-mcp-com

An MCP server that lets Claude (or any MCP client) control Microsoft Outlook desktop on Windows through the Win32 COM API — read and send email, manage your calendar, save attachments, and work with tasks and notes, all against the Outlook profile you are already signed in to. No Azure app registration, no Graph API tokens.

⚠️ Requirements & Limitations

This package is Windows-only and requires:

• Windows 10 or Windows 11 (classic Outlook COM API support)
• Python 3.10, 3.11, 3.12, or 3.13
• Classic Outlook desktop (Microsoft 365 / Office 2016+)

  The "new Outlook" (olk.exe) does not expose a COM API and will not work with this server.

• A configured Outlook mail profile with your account already signed in.

Not supported:

• macOS, Linux, or other Unix-like systems
• The new Outlook (UWP/Store app)
• Outlook Web Access (OWA) or cloud-only accounts
• The test suite runs on any OS (COM calls are mocked), but the actual server only works on Windows.

Installation

git clone https://github.com/adamkopelman/outlook-mcp.git
cd outlook-mcp
pip install .

This installs the outlook-mcp console command (and pywin32 on Windows).

Hooking it up to Claude

As a Claude Code plugin (recommended for Claude Code) — this repo is itself a plugin (.claude-plugin/plugin.json) that registers the outlook MCP server for you. After pip install . (above), either:

# Try it locally without installing anything into Claude Code's config:
claude --plugin-dir /path/to/outlook-mcp

# Or install it properly, from a local checkout or directly from GitHub:
claude plugin install outlook-mcp@/path/to/outlook-mcp
claude plugin install outlook-mcp@github.com/adamkopelman/outlook-mcp

The plugin launches the server as python -m outlook_mcp rather than via the outlook-mcp console script, so it works even if pip's script directory isn't on PATH — it just needs outlook_mcp importable by whichever python is first on PATH.

Claude Desktop — add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "outlook": {
      "command": "outlook-mcp"
    }
  }
}

If outlook-mcp isn't on PATH, use the full interpreter instead:

{
  "mcpServers": {
    "outlook": {
      "command": "C:\\Path\\To\\python.exe",
      "args": ["-m", "outlook_mcp"]
    }
  }
}

Claude Code (manual, without the plugin):

claude mcp add outlook -- outlook-mcp

Tools

Items are addressed by an opaque id returned from list/search tools. Ids change when an item moves folders — move_email returns the new id, and a stale id produces a clear "item not found" error.

Security notes

• send_email, reply_email, create_event (with attendees) and respond_to_meeting act immediately as the signed-in Outlook user, with no confirmation step inside the server. If you want a human in the loop, prefer create_draft / send=false, or deny the sending tools in your MCP client's permission settings.
• Outlook's object model guard may show a "A program is trying to send an e-mail message on your behalf" prompt, typically when no up-to-date antivirus is registered with Windows or group policy demands it. The prompt blocks the tool call until answered. Do not disable Outlook security to avoid it.
• save_attachments writes to any local path the MCP client asks for.

Troubleshooting

• "Outlook is not available..." — you're not on Windows, or classic Outlook isn't installed.
• The first tool call may take a few seconds while Outlook launches.
• "Item not found" — the id went stale (item moved or was deleted); list/search again to get a fresh id.
• Date filters use Outlook's JET format internally; if search_emails with since_days misbehaves on a heavily localized system, try without it and filter by eye.

Development

pip install -e .[dev]
pytest

The COM layer lives in outlook_mcp/outlook/client.py behind the OutlookClientBase interface (outlook_mcp/outlook/base.py); tests run on any OS against an in-memory fake (tests/conftest.py).

License

MIT — see LICENSE.