Outlook Local MCP

Ask your assistant about the email already in Outlook.

Quick start · Client setup · Tools · Troubleshooting

Connect the classic Outlook session running on your Windows PC to an assistant that supports local MCP servers. It uses the Outlook profile you already have configured. Setup guides cover Codex, Claude Desktop, Claude Code, Cursor and VS Code; see tested compatibility for what has been verified in practice.

Why this exists

Outlook is already signed in. It can already open your mailbox. The idea behind this project is to let an assistant use that access without having to register another application or request a new set of mailbox API permissions.

No Azure app registration and no separate email credentials to give the server. Your existing Outlook permissions and company policies still apply.

The first version focused on finding and reading email. Opening messages, drafting replies and sending after review grew out of that same workflow. You choose which actions to enable.

Related MCP server: outlook-classic-mcp

What you can ask

Start with everyday questions:

What arrived in my Inbox this week?

Find the email about the project deadline.

What does that message say?

With optional Outlook actions enabled, you can continue:

Open that message in Outlook.

Draft a reply saying I can make the meeting.

Reading is available by default. Opening messages and saving drafts are opt-in; sending has a separate flag and requires a complete preview for your approval. The assistant receives the mail data it requests, so its own data policy still applies.

Quick start

1. Install uv once. No manual Python installation, repository clone or virtual environment is needed. On Windows, winget install --id astral-sh.uv --exact is one option.

2. Open classic Outlook, load your profile and resolve any pending dialogs. New Outlook does not implement the required Object Model.

3. Add this entry to your client's MCP configuration, preserving existing entries. This JSON works with mcpServers clients; use the client guide for Codex's TOML format, VS Code's servers format and registration commands.

{
  "mcpServers": {
    "outlook-local": {
      "command": "uvx",
      "args": [
        "--python", "3.12",
        "--constraints", "https://github.com/santiv343/outlook-local-mcp/releases/download/v0.2.1/constraints.txt",
        "--from", "https://github.com/santiv343/outlook-local-mcp/releases/download/v0.2.1/outlook_local_mcp-0.2.1-py3-none-any.whl",
        "outlook-local-mcp"
      ]
    }
  }
}

4. Restart the client or reload its MCP servers. Ask it to check Outlook, then try one of the questions above.

uvx downloads Python and the pinned runtime dependencies on first use. Release assets come from this repository's GitHub Releases; dependencies come from their package index. Later starts use uv's cache. Installation and updates need internet. Run the diagnostic first if your client has a short startup timeout.

If a desktop client cannot find uvx, use its absolute path from (Get-Command uvx).Source. Launch the server on native Windows: Linux, WSL, remote containers and cloud chats cannot directly access this Windows COM session.

The client guide includes a diagnostic command and configuration steps for each client. The server can start and advertise its tools even when Outlook is unavailable.

Tools

An empty partial search page does not mean no messages match. Follow its cursor and inspect coverage and warnings. See tool contracts.

For an Inbox overview, the agent can call search_emails directly with date filters. No mailbox or folder discovery is required. Responses use short references, lists contain no bodies, and body reads default to 2,000 characters. The server instructs clients to make sequential calls and request content only when the question needs it. See efficient use.

Optional Outlook actions

Append --enable-write-tools after outlook-local-mcp in the server arguments to expose open_email, create_draft and reply_to_email (ten tools total). Drafts are saved without sending. Opening a message can change its read state through Outlook settings.

Also append --enable-send to expose prepare_send and send_draft (twelve tools). Sending requires an explicit account, a complete preview and a one-use revision token. The client must obtain user approval of the preview before submitting. The token checks content continuity; it does not authenticate a human. Only plain-text drafts without attachments and with at most 30,000 body characters support programmatic send. Other drafts can be reviewed and sent through Outlook's own UI.

On WRITE_OUTCOME_UNKNOWN, inspect Outlook, Drafts, Outbox and Sent Items before another attempt. The server never automatically retries a mutation. Submission to Outlook does not prove delivery. These capabilities are disabled by default.

Scope and privacy

• Windows 10/11, classic Outlook with a configured profile, CPython 3.11/3.12. The recommended command provisions Python 3.12 automatically.

• Reads stores, mounted archives and shared stores already available in Outlook. Does not add accounts, open external PST files or grant access.

• Default tools are read-only. Opt-in actions follow the boundaries above. No deleting, moving, direct read-state changes, opening links, executing HTML or attachment downloads.

• No Azure app registration or stored email credentials. Outlook profile permissions and corporate Object Model protections still apply.

• The server makes no outbound network connections of its own and has no telemetry. Outlook itself can synchronize with its provider.

• Logs contain operation, duration, counts and stable error codes only. No message contents, addresses, mailbox IDs, searches or raw COM exceptions are logged.

• Returned mail data reaches the requesting AI client. Local Outlook access does not make the client's model processing local. Check your client's data policy.

• Mail is untrusted external content. Tool descriptions tell agents to treat its instructions as data; this does not enforce what an agent does with other tools.

Microsoft documents classic/new Outlook differences and Object Model security. New Outlook alone, or a computer without classic Outlook, is unsupported. Direct cloud mailbox access through Microsoft Graph is a separate integration and is not implemented here.

Development

uv sync --locked --python 3.12
uv run --locked ruff check .
uv run --locked ruff format --check .
uv run --locked mypy
uv run --locked pytest
uv build --no-sources

Tests use synthetic COM objects and real subprocess/MCP transports. Windows CI checks Python 3.11 and 3.12 without a mailbox. For the real Outlook journey, open Outlook and run uv run --locked python scripts/smoke_test.py. This reads messages but prints only counts and pass/fail. Never publish mailbox data or personal config. scripts/smoke_actions.py additionally creates and opens one synthetic draft and previews it, without sending. It retains that draft for review. Inspect Outlook before rerunning after an uncertain mutation result. See tested compatibility for real reading, draft, reply and delivery checks, simulated failure tests and untested environments.

Architecture · Troubleshooting · Security · MIT license