exchange-ai-connector
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@exchange-ai-connector show me my unread emails from today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
exchange-ai-connector
An MCP server that lets an AI agent read and act on your Microsoft 365 / Outlook email and calendar, with every state-changing action (sending mail, creating an event) gated by your MCP client's confirmation prompt.
On PyPI: uvx exchange-ai-connector
or pipx install exchange-ai-connector. See Setup.
Tools
Tool | Kind | What it does |
| read-only | List messages in a folder (default inbox) |
| read-only | Read one message in full |
| read-only | Read a whole conversation, oldest → newest |
| gated | Send or reply — client confirms first |
| read-only | List upcoming calendar events |
| read-only | Read one event in full |
| read-only | Free/busy for you (+ others) — work/school only |
| gated | Create an event, optionally inviting attendees |
Related MCP server: outlook-mcp
How the human-in-the-loop gate works
The read-only tools run freely. The two gated tools (send_email,
create_event) are the only ones that change the outside world; they are
annotated as destructive, so your MCP client (e.g. Claude Desktop) shows you the
exact arguments — recipients, subject, body / event details — and waits for your
approval before running. The draft you review is the agent's proposed
arguments; nothing is stored half-sent. Reject and it vanishes.
Account-type support
Account type | Calendar read/create |
| |
Work / school (Microsoft 365) | ✅ | ✅ | ✅ |
Personal (outlook.com / hotmail) | ✅ | ✅ | ❌¹ |
¹ Graph's getSchedule (free/busy) is not available on personal Microsoft
accounts. check_availability returns a readable error there; every other tool
works.
Setup
1. Register an app in Microsoft Entra ID
Go to https://entra.microsoft.com → Identity → Applications → App registrations → New registration.
Name: anything (e.g.
exchange-ai-connector).Supported account types: Accounts in any organizational directory (multitenant) and personal Microsoft accounts.
Redirect URI: platform Public client/native (mobile & desktop), value
http://localhost:8400.Click Register, then copy the Application (client) ID from the overview page — you'll need it below.
2. Add Microsoft Graph permissions
In your app → API permissions → Add a permission → Microsoft Graph → Delegated permissions.
Add:
Mail.Read,Mail.Send,Calendars.ReadWrite.Personal account: nothing more — you consent in the browser on first run. Work/school account: a tenant admin may need to click Grant admin consent.
Adding
Calendars.ReadWritelater (e.g. after using email-only) triggers a one-time browser re-consent on the next run. See Re-consent below.
3. Install
Pick one:
uvx (recommended — no clone, no venv). Requires uv.
Nothing to install ahead of time — uvx fetches and runs the command in a
throwaway environment. It's used directly in the Claude Desktop config below, so
you can skip straight to that section.
pipx — puts the exchange-ai-connector command on your PATH globally:
pipx install exchange-ai-connector
# or an unreleased version straight from source:
pipx install git+https://github.com/wteja/exchange-ai-connectorFrom source (for development):
git clone https://github.com/wteja/exchange-ai-connector
cd exchange-ai-connector
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
which exchange-ai-connector # note this path for the Claude Desktop config4. Configure environment
export EXCHANGE_AI_CLIENT_ID="<your-app-client-id>"
# optional — pin to one tenant instead of the multi-tenant default:
# export EXCHANGE_AI_AUTHORITY="https://login.microsoftonline.com/<tenant-id>"
# optional — override the auto-detected timezone (default: /etc/localtime, else UTC):
# export EXCHANGE_AI_TIMEZONE="Asia/Bangkok"EXCHANGE_AI_CLIENT_ID is required; the other two are optional.
Claude Desktop setup
Edit (on macOS) ~/Library/Application Support/Claude/claude_desktop_config.json
and add an exchange-ai server under mcpServers. The uvx form needs no clone
or venv — it fetches exchange-ai-connector from PyPI and runs it:
{
"mcpServers": {
"exchange-ai": {
"command": "/opt/homebrew/bin/uvx",
"args": ["exchange-ai-connector"],
"env": {
"EXCHANGE_AI_CLIENT_ID": "<your-app-client-id>",
"EXCHANGE_AI_TIMEZONE": "Asia/Bangkok"
}
}
}
}Use the absolute path to
uvx(which uvx— e.g./opt/homebrew/bin/uvxon Apple-Silicon Homebrew). Claude Desktop is a GUI app and does not inherit your shell'sPATH, so a bare"uvx"won't be found.
Useful variants for the args:
Pin a version (reproducible; uses uv's cache without re-resolving — handy if your network can't always reach PyPI):
["exchange-ai-connector@0.2.0"]Run an unreleased version from GitHub:
["--from", "git+https://github.com/wteja/exchange-ai-connector", "exchange-ai-connector"]
If you installed from source into a venv instead, point command at the
binary's absolute path (same PATH reason as above):
"command": "/ABSOLUTE/PATH/TO/.venv/bin/exchange-ai-connector"Claude Code (.mcp.json)
For Claude Code, put the same server under mcpServers in a .mcp.json at your
project root (Claude Code expands ${VAR} from your environment):
{
"mcpServers": {
"exchange-ai": {
"command": "uvx",
"args": ["exchange-ai-connector"],
"env": {
"EXCHANGE_AI_CLIENT_ID": "${EXCHANGE_AI_CLIENT_ID}",
"EXCHANGE_AI_TIMEZONE": "Asia/Bangkok"
}
}
}
}EXCHANGE_AI_TIMEZONE is optional — omit it to auto-detect from the system
(/etc/localtime, falling back to UTC). command can be a bare uvx here
because Claude Code runs from your shell and inherits its PATH (unlike the
Claude Desktop GUI, which needs the absolute path).
Then fully quit Claude Desktop (Cmd+Q) and reopen it. The exchange-ai
server and its tools should appear in the tools/connector list.
On the first tool call a browser opens for sign-in and consent; the token is cached in your OS keychain and refreshed silently afterward.
Suggested approvals: allow the read-only tools (list_emails, read_email,
read_thread, list_events, read_event, check_availability) to run without
asking, but leave send_email and create_event on ask every time — that's
the human-in-the-loop gate doing its job.
Run standalone (without a client)
exchange-ai-connectorIt's a stdio MCP server, so it waits silently for a client to connect — there's no interactive output. This is mainly useful for confirming it starts.
Example usage (sample prompts)
Once it's wired into Claude Desktop, drive it in plain language. Examples:
Reading email
"List my latest 10 emails."
"Show me unread emails from this week."
"Read the full email from Alice about the invoice."
"Show me the whole thread for that conversation."
Sending email (gated — you'll approve the draft)
"Reply to Alice's email saying I'll have the report by Friday."
"Send an email to bob@example.com, subject 'Lunch?', asking if he's free Thursday."
"Forward the invoice email to accounting@example.com with a short note."
Reading the calendar
"What's on my calendar this week?"
"Read the details of my 2pm meeting tomorrow."
"Am I free tomorrow 2–3pm?" (work/school accounts only)
"When are alice@contoso.com and I both free Thursday afternoon?" (work/school only)
Creating events (gated — you'll approve the details)
"Create a 30-minute event tomorrow at 2pm titled 'Project sync'."
"Schedule a 1-hour meeting Friday 10am called 'Design review', invite alice@contoso.com and bob@contoso.com."
"Block 9–11am Monday for focus time."
For the gated actions, Claude Desktop shows the exact send_email(...) /
create_event(...) arguments and waits for your Approve / Deny. Want a
change? Tell the agent ("make it 45 minutes", "cc my manager") and it re-proposes.
Audit log
Every gated action appends one JSON line to
~/.exchange-ai-connector/audit.log:
Sends:
{ts, to, subject[, reply_to_id]}Events:
{ts, kind:"event", subject, start[, attendees]}
Append-only JSONL, grep-able:
grep '"kind": "event"' ~/.exchange-ai-connector/audit.logRe-consent / token cache
The OAuth token is cached in your OS keychain (service
exchange-ai-connector, account msal-token-cache) and refreshed silently. The
cached token only carries the scopes you consented to. If you add a scope
(e.g. enabling calendar after email-only), clear the cache so the next run
re-prompts the browser with the new scopes:
python -c "import keyring; keyring.delete_password('exchange-ai-connector','msal-token-cache')"("Not found" just means there was no cache to clear.) Then restart your client.
Scope
v1: email — list/read/thread + gated send.
v2 (this release): calendar — list/read events, free/busy availability, and gated
create_event.
A standalone web approval UI, app-only auth, and multi-account approval remain
deliberately out of scope; see the design specs under docs/superpowers/specs/.
Available Tools
8 toolscheck_availabilityARead-only
Free/busy over a window. Times are naive local, e.g. '2026-07-02T14:00:00'. attendees defaults to just you. Read-only.
Inputs: end (required), start (required), interval, attendees. Returns: result
create_eventADestructive
Create a calendar event; emails invites to attendees. Times are naive local, e.g. '2026-07-02T14:00:00'. IRREVERSIBLE — the client must confirm before allowing.
Inputs: end (required), start (required), subject (required), body, +2 more.
list_emailsBRead-only
List messages in a mail folder. Read-only.
Inputs: top, query, folder. Returns: result
list_eventsBRead-only
List upcoming calendar events, soonest first. Read-only.
Inputs: top. Returns: result
read_emailBRead-only
Read one message in full. Read-only.
Inputs: message_id (required).
read_eventCRead-only
Read one calendar event in full. Read-only.
Inputs: event_id (required).
read_threadCRead-only
Read all messages in a conversation, oldest first. Read-only.
Inputs: conversation_id (required). Returns: result
send_emailADestructive
Send or reply to an email. IRREVERSIBLE — the client must confirm before allowing.
Inputs: to (required), body (required), subject (required), cc, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct operation within either the calendar or email domain, with no overlapping purposes. check_availability, create_event, list_events, and read_event are clearly separate; similarly for email tools.
All tools follow a consistent verb_noun pattern using snake_case (e.g., check_availability, list_emails). No mixing of conventions or ambiguous verbs.
With 8 tools covering both email and calendar operations, the count is well-scoped for the connector's purpose. Each tool serves a clear function without superfluous entries.
The tool surface covers essential read and create operations but lacks update and delete for calendar events, and email deletion or folder management. These are notable gaps for a full lifecycle.
Maintenance
Related MCP Connectors
Every email and calendar account you connect, for AI agents, with permissions and approvals.
Let your AI agent read and act on your Mail, Calendar, Contacts and more. Works with iCloud.
Governed email for AI agents: a sandbox inbox to read and send from, human approval to go external.
Email, calendar and contacts for AI agents: Gmail, Microsoft 365 and IMAP accounts behind one API.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Microsoft Outlook via the Microsoft Graph API for managing emails and calendar events. It allows users to read and send emails, list messages, and create calendar appointments with automatic Teams links.1ISC
- AlicenseBqualityCmaintenanceEnables AI assistants to manage Microsoft Outlook email and calendar through the Microsoft Graph API, including reading, sending, searching emails, and handling calendar events.4331MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with Microsoft 365 Outlook Mail, allowing email operations via natural language.119 npmMIT
- AlicenseAqualityBmaintenanceEnables AI assistants to securely read, search, draft, and send Outlook emails, manage calendar events, and access mailbox folders through a local MAPI connection to Windows Outlook, with human-in-the-loop safeguards.91MIT