Outlook 邮件日历联系人 MCP 服务

Outlook MCP Server

MCP (Model Context Protocol) server that connects Claude to Microsoft Outlook via the Microsoft Graph API. 28 tools covering email, calendar, contacts and profile, over stdio or streamable HTTP.

Features

Email

Calendar

Contacts

Enough to merge duplicates: find them, read the one to drop, carry what it has over to the one kept, delete it. And to retire a folder a phone used to sync into: move its contacts out, then delete it.

Profile

Quick start

python -m venv venv && venv\Scripts\activate   # macOS/Linux: source venv/bin/activate
pip install -r requirements.txt

cp outlook_mcp.toml.example outlook_mcp.toml   # then fill in [credentials]
python outlook_mcp_auth.py  # sign in once; tokens land in ~/.outlook_mcp_token_cache.json

python outlook_mcp_server.py

That covers a local stdio server. The full procedure, including the Azure app registration and the HTTP transport, is in docs/SETUP.md. Personal Microsoft accounts have their own prerequisites: see docs/SETUP_PERSONAL_ACCOUNTS.md.

Transports

One entry point, two transports, chosen by outlook_mcp.toml rather than by a flag. Without that file the server runs on stdio. The app registration is in that same file, and no credential ever travels in a request: what a call carries is at most the identity of the user it acts for.

An HTTP server may only bind loopback, and refuses to start otherwise: the identity header is trustworthy exactly because the reverse proxy is the only way in. See docs/SETUP.md.

Deployment

./scripts/deploy.sh --target root@server.example.com

Copies the checkout to a Linux host, builds a virtual environment, installs the configuration and a systemd unit, and starts the service. --dir, --service-user, --service-name, --config and --dry-run are all accepted; the details are in docs/SETUP.md. Only what git tracks is uploaded, so a local outlook_mcp.toml never travels by accident.

Project Structure

OutlookMCP/
├── outlook_mcp/                # The package
│   ├── app.py                  # MCPServer instance + lifespan
│   ├── server.py               # Entry point: argparse, config, run
│   ├── config.py               # outlook_mcp.toml: the whole configuration
│   ├── credentials.py          # Principal resolution + GraphClientPool
│   ├── auth.py                 # AuthManager (MSAL) + GraphClient (httpx)
│   ├── authorize.py            # OAuth2 authorization code flow
│   ├── enroll.py               # /oauth/login + /oauth/callback (HTTP deployments)
│   ├── downloads.py            # /attachments/<token>: handing a file to a remote caller
│   ├── folders.py              # Mail folder resolution and rendering
│   ├── events.py               # All-day events the way Graph insists on them
│   ├── contacts.py             # Every contact folder, name matching, birthdays
│   ├── attachments.py          # Inline and upload-session attachment writing
│   ├── helpers.py              # Formatting, error handling, $filter validation
│   ├── models.py               # Pydantic input models
│   └── tools/                  # The 28 tools
│       ├── mail.py
│       ├── calendar.py
│       ├── contacts.py
│       └── profile.py
├── tests/
│   ├── unit/                   # pytest, no network
│   └── integration/            # scripts that call the real Graph API
├── scripts/
│   ├── deploy.sh               # Install on a Linux host as a systemd service
│   └── generate-claude-config.*  # Claude Desktop config generators
├── docs/
│   ├── SETUP.md                # Full setup guide
│   └── SETUP_PERSONAL_ACCOUNTS.md
├── contrib/                    # Deployment helpers, not part of the server
│   └── systemd/                # The unit template deploy.sh renders
├── outlook_mcp_server.py       # Entry point wrapper (same as the outlook-mcp command)
├── outlook_mcp_auth.py         # Wrapper (same as the outlook-mcp-auth command)
├── outlook_mcp.toml.example    # The configuration template
└── pyproject.toml              # Package metadata, dependencies, pytest config

Usage Examples with Claude

Once configured, you can ask Claude:

• "Show me my unread emails"
• "Send an email to mario@example.com with subject 'Project Proposal'"
• "What meetings do I have tomorrow?"
• "Create a Teams meeting with the team at 3:00 PM on Monday"
• "Archive all newsletter emails"
• "Reply to that email saying I confirm"
• "Cancel Friday's meeting"
• "Accept the meeting invitation for tomorrow"
• "The Birthdays calendar shows Gabriele twice on 7 June: merge the duplicate contacts"
• "My phone no longer syncs: move its contacts into Contacts and delete its folder"

Testing

pytest                                          # unit tests, no network, no credentials
python tests/integration/test_mcp_server.py     # stdio, real Graph calls
python tests/integration/test_http_server.py    # HTTP, identity sent as a header

pytest collects tests/unit only: the TOML config loader, the principal resolution, the token cache layout and the enrollment bookkeeping, all pure logic. The two integration scripts need a valid token cache and a working app registration, so they are run by hand; --quick and --verbose are accepted.

test_http_server.py starts the server on a free port with a temporary outlook_mcp.toml, enrols a throwaway identity, and drives it with nothing but an X-Auth-Email header. It checks the refusals too: no header, and a user who was never enrolled.

Security

• OAuth2 tokens are stored locally in ~/.outlook_mcp_token_cache.json, or one file per user under ~/.outlook_mcp/caches/ in an HTTP deployment, created 0600 before anything is written into them
• The client secret lives only in outlook_mcp.toml, never on the wire, and is never written to logs
• Token refresh is handled automatically by MSAL
• To revoke access: account.microsoft.com/privacy > App permissions

Troubleshooting