graph-mcp
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., "@graph-mcp find my latest email from Sarah and summarize the attached PDF"
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.
graph-mcp
A small read-only MCP server for Microsoft Graph. It gives any MCP client (Claude Code, Claude Desktop, Codex, VS Code, Cursor, Gemini CLI, or your own agent) access to a Microsoft account's:
Outlook mail: search, list, read messages, read attachments
OneDrive: browse, search, read files, including files others shared with you
OneNote: notebooks, sections, pages
Calendar events and contacts
Word, Excel, PowerPoint and PDF files are converted to text in memory (with MarkItDown); nothing is written to disk unless you ask for it. All dates and times, shown and given, are in your time zone.
It works with personal Microsoft accounts (outlook.com, hotmail.com, live.com) and, with a different tenant setting, with work or school accounts.
Status: early, personal project. Licensed under MIT.
Read-only, twice over
The sign-in only grants read permissions:
User.Read,Mail.Read,Files.Read.All,Notes.Read,Calendars.Read,Calendars.Read.Shared,Contacts.Read(plusoffline_accessfor staying signed in). Microsoft refuses any write with this token, whatever the code does.The code only reads: the Graph client has no method except GET, and every tool is marked read-only for MCP clients.
Content of mails, files and notes reaches the agent as data. The server's instructions tell agents to treat it as data, never as instructions, but as with any tool that reads untrusted text, keep that in mind when you let an agent act on what it read.
Related MCP server: outlook-evidence-mcp
Setup
1. Register an app with Microsoft (once, about 5 minutes)
Both ways of running it need your own app registration, which gives you a client ID. It's free.
Sign in at portal.azure.com and open Microsoft Entra ID.
With a personal account you may see "Selected user account does not exist in tenant 'Microsoft Services'": your account has no directory of its own. Create a free Azure account with the same Microsoft account; that gives you a Default Directory. App registrations cost nothing; you're only charged if you upgrade to pay-as-you-go and create paid resources.
App registrations → New registration. Name: anything (e.g.
graph-mcp). Supported account types: Personal Microsoft accounts only (or "any organizational directory and personal accounts"). Leave the redirect URI empty for now. Register.Authentication: set Allow public client flows to Yes. Then Add a platform → Mobile and desktop applications with the custom redirect URI
http://localhost, for the browser sign-in (see the sign-in steps below). Save.API permissions → Add a permission → Microsoft Graph → Delegated permissions:
Mail.Read,Files.Read.All,Notes.Read,Calendars.Read,Calendars.Read.Shared,Contacts.Read,offline_access(User.Readis already there). TakeNotes.Read, notNotes.Read.All: OneNote rejects every request from a personal account whose token hasNotes.Read.All. With a personal account there's no admin consent; you approve them when you sign in.Copy the Application (client) ID from Overview. It's an identifier, not a secret. Don't create a client secret: this is a public client.
2. Choose how to run it
A. On this machine | B. In Docker | |
For | Agents on the same computer | A home server that agents on several machines use |
Agents talk to it over | stdio (each agent starts | HTTP with a Bearer token |
The sign-in lives in | Your OS keychain | A Docker volume |
Steps | A1–A3 below | B1–B5 below |
You can use both; each keeps its own sign-in.
Option A: on this machine
A1. Install with uv, as a command on your PATH:
uv tool install git+https://github.com/cart1984/graph-mcpOr from a local checkout (edits take effect right away): uv tool install --editable ~/projects/graph-mcp.
A2. Sign in (once per machine):
GRAPH_MCP_CLIENT_ID=<your client id> graph-mcp loginIt prints a code; enter it at microsoft.com/devicelogin and approve the permissions.
If the page rejects the code ("The code you entered has expired" or "That code didn't work" right after you enter it), sign in through the browser instead. It opens Microsoft's sign-in page and catches the answer on http://localhost (the redirect URI from step 1.3):
GRAPH_MCP_CLIENT_ID=<your client id> graph-mcp login --browsergraph-mcp status shows who is signed in. The sign-in stays valid as long as it's used at least every 90 days or so; if it lapses, tools answer with "run graph-mcp login". All agents on the machine share this one sign-in.
A3. Add it to your agents. Every client starts the same command, graph-mcp, with GRAPH_MCP_CLIENT_ID set. Personal accounts need nothing else.
Claude Code:
claude mcp add --scope user graph -e GRAPH_MCP_CLIENT_ID=<id> -- graph-mcpClaude Desktop, Cursor, Gemini CLI (claude_desktop_config.json, ~/.cursor/mcp.json, ~/.gemini/settings.json):
{
"mcpServers": {
"graph": {
"command": "graph-mcp",
"env": { "GRAPH_MCP_CLIENT_ID": "<id>" }
}
}
}GUI apps on macOS may not see your shell's PATH; if the server doesn't start, use the full path from which graph-mcp (usually ~/.local/bin/graph-mcp).
VS Code (user or workspace mcp.json):
{
"servers": {
"graph": {
"type": "stdio",
"command": "graph-mcp",
"env": { "GRAPH_MCP_CLIENT_ID": "<id>" }
}
}
}Codex (~/.codex/config.toml):
[mcp_servers.graph]
command = "graph-mcp"
env = { GRAPH_MCP_CLIENT_ID = "<id>" }Option B: in Docker
compose.yaml runs the HTTP server in a locked-down container: read-only file system, no capabilities, a non-root user, the port on one address only, and the sign-in in a named volume. Files are converted in memory and never kept.
B1. Get the code and write the settings on the machine that will run it:
git clone https://github.com/cart1984/graph-mcp && cd graph-mcp
echo "GRAPH_MCP_CLIENT_ID=<your client id>" > .env
echo "GRAPH_MCP_TOKEN=$(openssl rand -hex 32)" >> .env
echo "GRAPH_MCP_BIND=<this machine's address on your clients' network>" >> .env
echo "TZ=America/New_York" >> .env # your time zone
chmod 600 .envGRAPH_MCP_TOKEN is what agents must send; anyone who has it can read your mail. GRAPH_MCP_BIND is required: the port is published on that address only, never on every interface.
B2. Build (the image is about 1 GB, mostly the document converters' dependencies):
docker compose buildB3. Sign in (once). With a device code:
docker compose run --rm graph login # enter the code at microsoft.com/deviceloginIf the page rejects the code, sign in through a browser on a computer that has graph-mcp installed (step A1), into a file instead of the keychain, then copy that file into the volume:
# on the computer with the browser:
GRAPH_MCP_CLIENT_ID=<id> GRAPH_MCP_TOKEN_CACHE=file graph-mcp login --browser # writes ~/.config/graph-mcp/token-cache.json
# put that file into the graph-mcp folder on the server (scp, or cp on the same machine), then there:
docker compose run --rm -T --entrypoint sh graph -c 'umask 077 && cat > /data/token-cache.json' < token-cache.json
rm token-cache.json # and the one in ~/.config/graph-mcp/ on the other computer: keep no copies aroundB4. Start it and check:
docker compose up -d
docker compose run --rm graph status # "Signed in as ...; token is valid."
docker compose ps # "healthy" once it's upThe container counts as healthy only while it has a sign-in (/healthz answers 503 "not signed in" otherwise), so docker compose ps also tells you when the sign-in is gone.
B5. Add it to your agents. They connect to http://<GRAPH_MCP_BIND>:8766/mcp with the header Authorization: Bearer <GRAPH_MCP_TOKEN>. Claude Code:
claude mcp add --scope user --transport http graph http://<host>:8766/mcp --header "Authorization: Bearer <token>"Other clients that support remote (Streamable HTTP) servers take the same URL and header in their config; for a client that only speaks stdio, bridge it with mcp-remote.
This is plain HTTP: the token and everything you read travel unencrypted. That's fine on a network you trust and inside a VPN. Anywhere else, put a TLS proxy in front (Caddy, for example) or don't expose it.
Updating: git pull && docker compose up -d --build. The sign-in stays in the volume.
Other ways to run
HTTP without Docker, e.g. on a server without containers:
GRAPH_MCP_CLIENT_ID=<id> GRAPH_MCP_TOKEN=$(openssl rand -hex 32) graph-mcp serve --transport http --host <address>The same URL, header and plain-HTTP warning apply as in B5. A token is required except on loopback, where --no-auth is allowed.
The sign-in as a file. Where there's no keychain (containers, headless Linux), the sign-in is kept in a file, ~/.config/graph-mcp/token-cache.json, mode 0600. It holds a refresh token and isn't encrypted: anyone who can read it can read your mail, so keep it (or the Docker volume) where only you can.
Keeping the originals. By default, files, attachments and OneNote pages are only converted to text. Set GRAPH_MCP_DOWNLOADS to a folder to also keep the originals there, for an agent on the same machine that needs the file itself (for example a long document whose text was cut off).
Settings
All settings are environment variables:
Variable | Default | What |
| (required) | Application (client) ID of your app registration |
|
|
|
|
|
|
|
| The sign-in file, when a file is used |
| (none: keep nothing) | Folder to keep the originals of files, attachments and pages in |
|
| IANA time zone (e.g. |
| (none) | Bearer token HTTP clients must send; at least 32 characters |
|
| HTTP port |
| (required in Docker) | The address |
Tools
Tool | What it does |
| Which account is signed in |
| Folders with unread/total counts |
| Search all mail, Outlook syntax ( |
| Newest messages in a folder, optionally unread only or since a date |
| One message in full, with its attachments listed |
| One attachment as text |
| List a folder by path |
| Search by name and content |
| Files and folders shared with you |
| One file as text, by id or path |
| Notebooks and their sections |
| Pages, newest first, optionally per section or by title |
| One page as text |
| Events in a date range (both days included), multi-day and all-day events shown with their days |
| Contacts by name |
Development
uv sync
uv run pytest
uv run ruff check && uv run ruff format --check
uv run pyrightTests run against a fake Graph and never touch the network; the fake fails any test whose code sends anything but GET. CI also builds the Docker image, starts the compose stack and checks its lockdown.
Available Tools
15 toolscalendar_eventsARead-only
List calendar events between two ISO dates or date-times, e.g. start=2026-11-16, end=2026-11-23 (both days included). Dates and times without an offset, and the times shown, are in the server's time zone (see the server instructions).
Inputs: end (required), start (required), top. Returns: result
contacts_searchARead-only
Find contacts whose name starts with query.
Inputs: query (required). Returns: result
mail_attachmentBRead-only
Read one attachment as text (PDF, Word, Excel, PowerPoint and more are converted).
Inputs: message_id (required), attachment_id (required). Returns: result
mail_foldersARead-only
List mail folders with unread and total counts.
Inputs: no named parameters. Returns: result
mail_getBRead-only
Read one message in full (plain-text body), with its attachment list.
Inputs: message_id (required). Returns: result
mail_listARead-only
List the newest messages in a folder. folder is a well-known name (inbox, sentitems, drafts, archive,
deleteditems, junkemail) or an id from mail_folders. since is an ISO date or date-time such as 2026-11-01,
in the server's time zone unless it has an offset.
Inputs: top, since, folder, unread_only. Returns: result
mail_searchARead-only
Search all mail with Outlook search syntax, e.g. invoice, from:amazon, subject:"tax return",
hasattachments:true dentist, received>=2026-10-01. Results are ranked by relevance.
Inputs: query (required), top. Returns: result
onedrive_listARead-only
List a OneDrive folder by path, e.g. / or /Documents/Taxes.
Inputs: path. Returns: result
onedrive_readARead-only
Read a OneDrive file as text. Give item_id (from a listing or search) or path
(e.g. /Documents/notes.docx). For a file shared with you, also give its drive_id.
Inputs: path, item_id, drive_id. Returns: result
onedrive_searchBRead-only
Search OneDrive by file name and content.
Inputs: query (required), top. Returns: result
onenote_notebooksBRead-only
List OneNote notebooks with their sections.
Inputs: no named parameters. Returns: result
onenote_pagesARead-only
List OneNote pages, newest first: across all notebooks, or in one section (id from onenote_notebooks).
title_contains filters by title.
Inputs: top, section_id, title_contains. Returns: result
onenote_readBRead-only
Read one OneNote page as text.
Inputs: page_id (required). Returns: result
whoamiARead-only
Show which Microsoft account is signed in.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool is scoped to a single domain and action, with domain prefixes (mail_, onedrive_, onenote_, calendar_, contacts_) making boundaries obvious. Within a domain, pairs like mail_list vs mail_search vs mail_get vs mail_attachment target clearly different retrieval modes, so an agent can pick correctly without guessing.
The dominant pattern is domain_noun/action in snake_case (mail_get, mail_folders, onedrive_read, onenote_pages, calendar_events), applied consistently across all five domains. The only outlier is `whoami`, which follows neither the prefix nor the verb_noun convention, a minor deviation in an otherwise predictable scheme.
Fifteen tools is squarely in the well-scoped range, and the surface is balanced across mail (5), OneDrive (4), OneNote (3), calendar (1), contacts (1) plus whoami. Every tool covers a distinct retrieval need with no filler or redundant variants.
The read-only surface is coherent and covers the core workflows: discover, search, list and read content across mail, files, notebooks and calendar. Gaps remain for a read-only model — no single-calendar-event fetch, no contact lookup by full detail beyond name prefix, and no mail thread/conversation view — but agents can work around these with the existing tools.
Maintenance
Related MCP Connectors
Permissioned access to Outlook, OneDrive and Teams via the user's own Microsoft account
Read email/chat conversations, messages, contacts and teams; draft, send and update threads.
Read-only access to your dotstell notes, bookmarks, tasks, people and meetings.
Read and search folders on your own computer with explicit consent. Files are never uploaded.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to Microsoft 365 services including SharePoint, OneDrive, Outlook, Teams, and Calendar through the Microsoft Graph API, enabling users to search, browse, and retrieve content across their M365 suite.2MIT
- AlicenseAqualityCmaintenanceEnables read-only search and export of Outlook emails and attachments with a chain-of-custody manifest for evidence collection.7MIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only access to classic desktop Outlook mailbox and calendar on Windows, enabling safe email and calendar queries without any write capabilities.MIT
- AlicenseNot gradedqualityBmaintenanceEnables read-only access to personal Microsoft Outlook mail, calendar, and contacts via the Microsoft Graph API using device-code authentication, without requiring the Outlook desktop app.MIT