teams-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
teams-mcp
Unofficial project. Not affiliated with, endorsed by, or supported by
Microsoft, University of Northwestern – St. Paul, or any employer. Automating
sign-in and internal APIs may violate Microsoft or tenant terms and can lead to
account lockout or other account action. Use it only with your own account and
read DISCLAIMER.md before you do. MIT licensed.
Token-efficient MCP server for Outlook mail and calendar, scheduling across
people, directory lookup, and Microsoft Teams chats/channels/messages via
Microsoft Graph. Seven op-dispatched tools with
compact output and a local calendar snapshot.
API split (the tested tenant): Outlook REST v2.0
(https://outlook.office.com/api/v2.0) is the primary API for mail, calendar and
scheduling; Microsoft Graph is used for directory search (/users) and for
Microsoft Teams (chats, channels, messages, channel creation), because Graph
app assignment for mail/calendar is blocked here (403).
Status: all seven tools and every advertised op are implemented. Mail and calendar
writes have explicit-argument and subject guards. Live probes covered
send, get, mark, move, create, update, delete, list, search,
thread, freebusy, suggest and snapshot. reply, forward, respond
and unsubscribe_apply were exercised end-to-end over MCP against a local mock
REST endpoint (never against the tenant). Teams was exercised live end to end:
status, list (teams/chats/channels), read, replies, one confirmed send,
and create → send → delete of a private channel (see docs/design.md
§12). Login/refresh is implemented in src/auth/* and consumed through
token.json; the Teams-web token has its own cache (below).
Safety modes
Start read-only. This README's registration snippets, mcp.example.json and
config.example.yaml all ship read-only, so a copy-paste agent cannot change a
real mailbox until you deliberately allow it. unsubscribe_apply is an
irreversible external action — a one-click opt-out is recorded by the third
party and cannot be undone — so it is off by default and capped when enabled.
Full threat model: SECURITY.md.
Control | Shipped example | Effect |
| on | Refuse every mutating op before any request: mail send/draft/send_draft/reply/forward/mark/move/ |
| off |
|
| 5 | Maximum external unsubscribe actions per local day, not apply calls: a message carrying both an https one-click URL and a |
| 30 | One global per-process token bucket for every mutating op: mail send/draft/send_draft/reply/forward/mark/move/ |
Teams adds refusals of its own, independent of read-only mode:
teams.send/teams.create/teams.delete need confirm: true. Posting into a
chat or channel this server did not create requires that exact target in the
operator allowlist teams.allowed_targets (chat:<chat_id> or
channel:<team_id>/<channel_id>); anything else is target_not_allowed before
any request, and there is no model-facing flag to widen it. teams.delete
additionally needs expected_name and only works on channels recorded in
teams-state.json (name_mismatch / target_not_created otherwise). Each
refusal happens before any write request.
Teams also validates the whole shape of a write before spending a rate token:
teams.create is channel-only and returns invalid_argument for a missing
or over-long argument list (kind=channel needs team_id and name, with at
most 20 optional members) and private_required for a channel without
private: true; a channel create in a team the signed-in user does not own
returns not_owner after one owner lookup. kind=chat is not accepted at all —
Graph requires every chat member to be an owner or guest, so this server never
creates a chat. Every Teams refusal is journaled, and
a refusal after the rate token was taken refunds it, so a rejected call cannot
exhaust the write budget. A delete whose channel is already gone (404/410 before
or during the request) answers {deleted: false, already_absent: true}, prunes
its teams-state.json row and writes exactly one already_absent journal line.
The model-facing settings.set refuses safety.*, invite_allowlist and
teams.allowed_targets: those keys are operator-owned, so an agent cannot enable
unsubscribe, raise a cap, switch off read-only or widen the Teams send allowlist.
Edit config.yaml or run node dist/cli.js settings set … from a shell instead.
Every write that reaches a tool's write path — allowed, refused by policy, or
blocked by read-only/rate-limit — is appended to
~/.cache/teams-mcp/write-audit.jsonl with a timestamp, tool/op, an id or
recipient count and an outcome; never message bodies or tokens. That includes
policy refusals and near misses: subject_mismatch, allowlist rejections
(recipient_not_allowed), protected-settings attempts (safety_key_protected),
read_only, rate_limited, cap_reached, mail confirmation_required /
no_recipients for send_draft, calendar conflict_detected /
conflict_check_failed, and every auth.login attempt.
Remove the read-only setting only for a trusted write task (drop
TEAMS_MCP_READ_ONLY from the env, or set safety.read_only: false), and put it
back afterwards. An agent cannot undo it on its own: settings.set is itself
blocked in read-only mode; an operator edits config.yaml or runs
node dist/cli.js settings set safety.read_only false from a shell.
Why these defaults exist: an early live-account test with an autonomous agent
performed bulk mailbox actions; the capability controls exist to prevent a
repeat. A read-only regression run with a cold agent was blocked before any
network call and wrote nothing, and a red-team review of this layer found and
fixed four gaps (rate limit scope,
unsubscribe cap accounting, operator-only safety.*, audit coverage). Design
rationale: docs/design.md §10.
Related MCP server: mcp-outlook-calendar
Install
Requires Node >= 22 (Node 26 tested). The server uses Promise.withResolvers
and AbortSignal.any; both need Node 22+.
Run it straight from GitHub with npx — no clone, no committed dist:
npx -y github:HenryGetz/teams-mcpThat is how a stdio MCP client should launch it (command: "npx", args: ["-y", "github:HenryGetz/teams-mcp"]). The first run downloads the repo, runs
npm install and the prepare build (tsc), then starts the server on stdio;
expect 60–90 s on a clean machine. Later launches still revalidate the git
ref and typically start in 10–40 s; pin a commit (github:HenryGetz/teams-mcp#<sha>)
or install globally if you want a fixed, faster start. Nothing is published to
npm.
Some MCP clients abort a server that has not finished initializing within 60 s, which that first install can exceed. Warm the cache once from a shell before you register the server:
npx -y github:HenryGetz/teams-mcp </dev/nullIt prints a ready line and exits on EOF, so client start-up only pays the
~10–40 s warm-path cost. A client with a stricter timeout should install globally
(npm install -g github:HenryGetz/teams-mcp) and use the teams-mcp bin.
The sign-in flow drives Chromium through Playwright, so install that browser
once on the machine that will run auth login:
npx playwright install chromiumThen sign in (auth login from your MCP client, or node dist/cli.js auth login); an interactive login takes roughly 25–60 s, and the token cache
makes later starts immediate.
Alternatives:
# global install, same git source
npm install -g github:HenryGetz/teams-mcp
teams-mcp
# from a checkout (development)
git clone https://github.com/HenryGetz/teams-mcp.git
cd teams-mcp
npm ci
npm run buildnpm pack produces a tarball that installs the same way (npm install -g ./teams-mcp-0.1.0.tgz). private: true in package.json prevents an accidental
npm publish; install it from this repository, not the registry.
Register with an MCP client
JSON (mcp.json, Claude Desktop, Cursor, VS Code):
{
"mcpServers": {
"teams": {
"command": "npx",
"args": ["-y", "github:HenryGetz/teams-mcp"],
"env": {
"TEAMS_MCP_TIMEZONE": "America/Chicago",
"TEAMS_MCP_READ_ONLY": "1"
}
}
}
}mcp.example.json is the same file, ready to copy. TEAMS_MCP_READ_ONLY=1 is
part of the shipped default: remove that line only for a trusted task that must
write (see Safety modes). A source checkout can use
"command": "node", "args": ["dist/index.js"], "cwd": "/absolute/path/to/teams-mcp"
instead, after npm run build. To have a CLI write the client config for you:
npx -y add-mcp github:HenryGetz/teams-mcp -a cursor -n teams \
--env TEAMS_MCP_TIMEZONE=America/Chicago --env TEAMS_MCP_READ_ONLY=1 -ySwap -a cursor for your client's identifier; the env flags are the same
read-only defaults as above.
Installed from git or a tarball, the teams-mcp bin is the entrypoint — drop
cwd and use "command": "teams-mcp" with no args. With npx, use
"command": "npx", "args": ["-y", "github:HenryGetz/teams-mcp"]. Do not use
npm install teams-mcp: that registry name is not this project. The
repo-relative form above is for a source checkout after npm run build.
YAML (opencode style):
mcp:
teams:
type: local
command: ["node", "/absolute/path/to/teams-mcp/dist/index.js"]
enabled: true
environment:
TEAMS_MCP_TIMEZONE: America/Chicago
TEAMS_MCP_READ_ONLY: "1"No secrets go in either file: credentials live in ~/.config/teams-mcp/token.json
(0600), written by the login flow. Config-file equivalent: safety.read_only: true
in config.example.yaml, which also ships read-only.
Environment variables win over the config file, so a stray
TEAMS_MCP_READ_ONLY=1 keeps an agent read-only even after you edit the YAML.
Tools
Tool | Ops | Live |
|
| all (login runs the real sign-in flow) |
|
| all implemented; send/list/search/get/thread/mark/move plus attachment metadata/content live-probed, reply/forward/draft/send_draft exercised against the mock REST endpoint |
|
| all implemented; agenda/respond exercised against the mock REST endpoint |
|
| all implemented; check/free covered by fixture tests over snapshot busy data |
|
| all |
|
| all |
|
| all (list/read/replies/send/private-channel create/delete exercised live; created channel deleted, 404 on re-read; chat creation is refused by the schema) |
Write behaviour worth knowing:
mail.attachmentsreturns metadata only — up to 20 rows of{id, name, content_type, size, is_inline}pluscountandtruncated— for an attachment-only message. It never requests content.mail.get_attachmentfetches one attachment byattachment_id.text/*andapplication/calendar*are decoded inline as UTF-8, cut at 20 000 chars withtext_truncated;text: trueforces that decode for other textual types (JSON,.eml). Every other type is saved to~/.cache/teams-mcp/attachments/(directory 0700, file 0600, sanitised basename plus a random suffix) and returned assaved: truewithpath. Decoded content over 10 MB returnsnote: "too_large"without saving; a reference attachment with no bytes returnsnote: "content_unavailable". Both ops are reads: allowed in read-only mode, no write token, and saved files are never opened or executed.Mail write responses echo the resolved addresses as
recipients: {to?, cc?, bcc?}(empty lists omitted) forsend,send_draft,reply,reply_allandforward, so confirming where a message went needs no follow-upmail.get. Forsend_draftthese are the draft's actual recipients, re-read immediately before sending.mail.sendneeds explicitto[],subjectandbody; it answers{ok, op:"send", recipient_count, recipients}plus a best-effortidwhen exactly one copy of the message can be found in Sent Items (matching subject and a short receive window), otherwise anoteinstead — Outlook returns 202 with no id and an id is never guessed. Recipients outsideinvite_allowlist(when set) are refused.mail.drafttakes the sameto[]/cc/bcc/subject/bodyand saves the message to Drafts; it returns{ok, id?, web_link?, note}and sends nothing. It is a write on every safety gate (read-only refuses it, it takes a rate token, allowlist checks apply, the attempt is audited).mail.send_draftneedsdraft_idandconfirm: true. It re-reads the live draft (a draft edited elsewhere may name new recipients), refuses when it has no recipients or any recipient is outsideinvite_allowlist, then sends it and reports the Sent Itemsid/notethe same waysenddoes. The rate token is refunded when the re-read or allowlist check refuses.mail.replyacceptsreply_all: true(REST/replyall): the reply reaches the sender plus every To/Cc address, and every derived address is checked againstinvite_allowlistbefore the send, so a reply-all that would leave the allowlist isrecipient_not_allowedwith nothing sent.mail.folderslists top-level folders in one page (max 50) as{id, name, total, unread, child_folders}withcountandtruncated(true on a full page). Read-only.Recipient/attendee values without
@are resolved through the tenant directory before any write: one match is used, several returnambiguous_recipientwith every candidate andneeds_disambiguation, none returnsrecipient_not_found. A name is never guessed. This applies tomail.send(to/cc/bcc),mail.forward, andcalendar.create/update.Mail list/search rows carry
conversation_id(usable asmail.thread'sthread_id).listwithfrom=<address>cannot use$orderbywith that filter (Exchange answersInefficientFilter) and a small$topwas seen returning the oldest matches, so it scans whole pages (50 at a time, at most 5), sorts the union newest-first client-side, returns the newesttop, and reportsscanned_pages, plustruncatedand a resumablenext_cursorwhen the 5-page cap stopped before the match set ran out.web_linkis omitted by default (include_web_link: truerestores it);include_unsubscribe: trueaddsunsub{has, one_click}so a newsletter can be found in one call, andinclude_unsubscribe_targets: trueadditionally inlinesurl/mailto(~1.2 KB over 25 rows; useunsubscribe_previewwhen you need the detail for one message).mail.getcaps the body at 4 000 chars by default (body_chars, max 20 000; raise it when the body matters).Every list/search row also carries
received_local— the received instant rendered in the configured timezone — so a caller can judge "today" without converting the UTCreceivedvalue itself.brief: truekeeps onlyid, subject, from, received, received_local, unread(plushas_attachmentswhen true), dropping preview, flag, conversation id and links.preview_chars(40–1000, defaultmax_results.preview_chars, shipped 300) caps thepreviewtext;include_body_preview: falseremoves it entirely and wins over anypreview_chars.mail.list/searchdeclaretopup to 50 in the schema, but the page is additionally capped bymax_results.mail(default 25, max 50). The config value is the operator's opt-in: an agent cannot exceed it per call, andtruncated/next_cursorreport when the cap cut the answer.mail.threadreturns compact rows by default.include_body: trueadds each message's body as text, cut at 500 chars (body_chars, max 2 000) withbody_truncated; HTML bodies are entity-decoded and newline-converted before the cut.top/cursorpage the conversation andtruncatedmarks a full page.mail.movereturns the message's new id.calendar.update/delete/respondrequireevent_idandexpected_subject; a mismatch returnssubject_mismatchand performs no write.calendar.updatealso appliesinvite_allowlistto new attendees.calendar.createdefaults: timezone from config, start at the next 15-minute boundary, durationdefault_duration_min; all-day events use local dates.duration_minsupplies the end whenendis absent (measured fromstart, or from the default start when both are omitted) and is rejected withinvalid_argumentwhen bothstartandendare given — passstart+duration_min, orstart+end. Astart/endwithoutZ/offset is read intimezone(a time the zone skips at a DST change is refused by name). Write responses are converted back to UTC using theTimeZoneechoed by the API, sostart,endandlocalalways describe the stored event.createandupdatereturnattendees_detail(email, name, type, status) exactly asgetdoes.calendar.create/updateacceptconflict_policy: warn|refuse|ignore(defaultwarn). The check reads the user's owncalendarviewfor[start, end), ignores events markedfree, and (on update) the event being edited.warnbooks and reportsconflicts(≤5 rows) plusconflict_countandconflict_warningwhen any overlap;refusereturnsconflict_detectedwithconflicts/conflict_countand writes nothing;ignoreskips the read. If the check itself failed underwarnthe write still happens and the result saysconflict_check: "unavailable". The read runs only after the read-only, rate-limit and allowlist guards, so a refused write issues no calendar read.calendar.updatetime fields:startalone moves the start and keeps the event's existing duration;endalone moves the end and keeps the start;duration_minderives the missing bound (withstart,end, or neither);shift_minmoves both bounds by a signed number of minutes keeping duration.shift_mincannot be combined withstart/end/duration_min, andduration_mincannot be combined with both bounds — those areinvalid_argumentbefore any request. Every successful update returnschanged{start_before, start_after, duration_before_min, duration_after_min}so the actual move is visible, and a time change triggers the conflict check above (a subject-only edit does not read the calendar).calendar.listomitsweb_linkby default (include_web_link: true);brief: truekeeps onlyid, subject, start, end, local, show_as.calendar.agendais the "what's my day" view: one compact row per event over a day or range, defaulting to today intimezone(whole local day, DST-safe across midnight; passstart/endfor another day or a multi-day range). Rows are{date, start_local, end_local, time, subject}— no attendees, location, organizer or web link — andtimeis09:00–09:30orall day.include_ids: falsedrops the event id; the defaulttruekeeps it so a row can be passed tocalendar.get.top(default 25, cap 50) plustruncated/next_cursorpage a long range. Read-only: no write token.availability.checkanswers one exact proposed slot:startandendare required (a missing bound isinvalid_argumentbefore any read), attendees default to the signed-in user, and the result isavailable(true only when every attendee is free),rangewith local labels, per-attendee rows{email, status, data_available, unknown}, overlappingconflicts(up to 5 with the trueconflict_count) andunknown: [emails]. An unknown mailbox makes the slot unverifiable —available: false, never a guess. It writes nothing and takes no write token, so it is the cheapest "can we meet at 3?" probe.availability.freelists explicit free windows rather than a ranked subset:start/enddefault to today..+7d,duration_mindefaults todefault_duration_min,working_hours_onlyis true by default,buffer_minpads around meetings, andmax_slots(≤20) caps the answer. It is computed from snapshot busy gaps locally — nofindmeetingtimes— and returnsslots[{start, end, local}],count,truncated,data_availableandunknown. Use it when the question is "what windows are open", not "pick one". Bothcheckandfreeare reads: available in read-only mode, no write token, no rate-limit token.availability.suggestreturns up tomax_candidatesranked slots inside the requestedstart/endonly (never the cached snapshot's wider range), honoursworking_hours_onlyinside that window, and clampsmax_candidatesto 20. It is a ranked subset, not every free window: the output reportsreturned,max_candidates,truncated, and (local search)total_available. Those are counts over the attendees with schedule data. Each candidate carriesverified/data_available— false (anddata_warningset) when any requested attendee has no schedule data — and whenfindmeetingtimesreturned a candidate with no per-attendee availability,freeis the string"unknown"plus adata_warningrather than a fabricatedn/n. Windows are capped at 366 days (local slot search is O(window/interval)). A request whose only attendee is the signed-in user falls back to the local snapshot search when the service returns candidates without per-attendee availability (free: "unknown"), so a self-only "when am I free" question still gets real slots instead of unverified ones. Usefreebusywhen you need the full busy view. Availability attendees accept names/aliases/addresses like mail and calendar, including forfreebusyandsnapshot.busynever containsstatus:"free"intervals (absence of a block means free;availability_viewdigits still encode free time). If the service cannot resolve an attendee's mailbox (a typo, a foreign address) it returns no working hours, which is not evidence of availability:freebusyreportsunknown: [emails], marks those rowsunknown: trueand omits their digits, whilesuggestexcludes them withexcluded_unknown_attendees+warning(or refuses when nobody resolves). Everyfreebusyattendee row also carriesdata_available(false means "the service returned nothing for this mailbox", not "free all day"), and the snapshot metadata records the mailboxes with data as an optionaldata_available[]list.mail.reply/forwardlook the sent copy up in Sent Items (same conversation, short window after the 202) and return itsidonly when exactly one copy matches; otherwise they return anoteand the message id stays discoverable vialist folder=sentitems.unsubscribe_applydoes nothing withoutconfirm: true; with it, it acts on at most the two targets of that one message (one https one-click POST and/or onemailtosendmail). No bulk unsubscribe, no mail deletion.people.searchreturns every match; multiple matches come back withambiguous: trueandneeds_disambiguationinstead of a silent pick.Input validation is strict at the boundary: each
to/cc/bcc/attendeeselement must be one addr-spec (a comma list or CRLF isinvalid_recipient),since/untilare parsed and canonicalised before they reach the provider filter, an unknown IANAtimezoneor impossible date isinvalid_argument, availability windows are capped at 366 days, andpeople.resolveaccepts at most 50 inputs per call.
Compact answers
Prefer the row-level views when the question is a summary, not a full record:
calendar.agenda for "what is my day", calendar.list brief: true for a
range, availability.check for one proposed slot and availability.free for
the open windows, and mail brief: true/preview_chars for triage. These
return fewer fields and shorter strings than the detail ops; the actual byte
saving depends on the mailbox and the window, so treat it as a habit rather than
a fixed promise. Reach for get/freebusy/snapshot when the details are
what the task needs.
Full contracts and rationale: docs/design.md.
Worked agent-facing examples (schedule with someone, triage/reply mail,
unsubscribe preview, person resolution): docs/usage.md.
Login, token cache and refresh flow: docs/auth.md.
Every environment variable: .env.example; every config key:
config.example.yaml.
Auth status
auth.status reads only the local token cache (offline, safe to poll).
authenticated is true when any cached audience has a fresh access token;
fresh_audiences names which (["outlook"], ["graph"], ["teams_web"], or a
combination), and reason is present only when none is fresh. Each row in
audiences carries its own fresh, seconds_left and scope_count, and the
payload always includes a teams_web row (freshness, source, expiry, path) so
the Teams-web cache is visible even when it is stale.
So a stale outlook token does not make a working Graph/Teams-web session look
signed out: mail and calendar may need auth.login while directory search, chat
reads, and channel reads/sends keep working. Conversely
fresh_audiences: ["outlook"] means Graph-only operations (Teams via the OWA
graph token, directory search) will fail with auth_required.
Microsoft Teams
Chats, team/channel metadata, channel messages and replies, plus three writes (message send; private-channel create; deletion of a private channel this server created). Chats themselves are never created by this server (see below). Teams needs a second credential, selected per operation, never by user choice:
OWA
graphtoken (the oneauth.loginmaintains): chats and chat messages, team and channel metadata, channel create and delete, and chat sends.Teams-web Graph token: channel messages, replies, team/channel rosters, and channel sends. In the tested tenant the OWA token has no
ChannelMessage.Read.All; the Teams web client (5e3ce6c0-2b1f-4285-8d4b-75ee78787346) mints a Graph token that does, so every channel-message read and every channel send uses it.
First use silently harvests the Teams web session from the persistent browser
profile — no password, no prompt, ~11–25 s (typically ~18–25 s warm) — then
persists it. After that, renewal is a headless refresh (typically 1–3 s) and no
browser opens. It is a separate cache:
~/.config/teams-mcp/teams-web-token.json (0600, own refresh lock).
~/.config/teams-mcp/teams-state.json (0600) is the ledger of chats and channels
this server created: it decides what may be written to and deleted.
Reads:
list kind=chatsacceptschat_type=group|oneOnOne|meetingandquery(topic or member name), applied across pages, and returnscount,scanned_pages,truncatedandnext_cursor— a filtered list is a complete answer, not one page. Duplicate ids from a mid-scan membership change are collapsed to the newest snapshot, and rows carrylast_updatedpluslast_message_preview/last_message_atwhen Graph exposes a preview (omitted otherwise, so same-titled chats stay distinguishable).readhides roster/system events by default (include_system: false): they are filtered before the page is filled, sotopcounts real messages —topmeans "exactly up to N real messages", never "the latest N", and defaults to 10 (cap 25). Message text is cut at 500 chars by default (text_chars, max 1 000);replieskeeps its 1 000-char default. Setinclude_system: trueto see them rendered as readable text. Paging reportstruncatedandnext_cursor.
Writes:
teams.sendandteams.createrequireconfirm: true.teams.createis channel-only.kind=chatis not in the tool schema and Graph would not accept it safely: every chat member must beownerorguest(roles: [], omitted roles and"member"all answer 400), so the only valid group chat grants every invitee ownership — and this app cannot delete it (noChat.ManageDeletion.All). Create group chats in Microsoft Teams, ask the operator to add the chat toteams.allowed_targets, thensendwithconfirm: true. Chats that already exist can be read and posted to when allowlisted.teams.create kind=channelneedsteam_id,nameandprivate: true(private_requiredotherwise: team-wide channels are never created), plus at most 20 optionalmembers(invalid_argumentbeyond that, before any lookup), and the signed-in user must be an owner of the team (not_ownerafter one owner lookup).Sending to a chat/channel this server did not create requires the exact target in
teams.allowed_targets—chat:<chat_id>orchannel:<team_id>/<channel_id>— set inconfig.yaml,TEAMS_MCP_TEAMS_ALLOWED_TARGETS, or via the shell CLI. Otherwise the call istarget_not_allowedand issues no request.settings.setrefuses the key, so an agent cannot widen its own send scope. Targets this server created are inteams-state.jsonand need no entry.Existing test chats still have both users as owners; Graph cannot change chat member roles here (no
ChatMember.ReadWrite*; a memberPATCHanswers 405 on v1.0 / 404 on beta), so correct that in the Teams UI. The diagnostic chat used during testing was deliberately left labelled and empty.teams.deleteis channel-only and narrower still: it needsconfirm: trueplusexpected_namematching the live channel name (elsename_mismatch), and the channel must be inteams-state.json— i.e. one this server created. Pre-existing channels and chats cannot be deleted here. It uses the OWA token, treats a 404/410 as already absent rather than an error (already_absent: true), and prunes the ledger entry either way.Read-only mode, the one global write rate limit and the audit journal apply exactly as they do to mail and calendar. Policy refusals are journaled too:
confirmation_required,target_not_allowed,target_not_created,name_mismatch,invalid_argument,private_required,not_ownerandalready_absent. A refusal that already took a rate token refunds it (thealready_absentprune included), and each delete attempt writes exactly one journal line.
Default posture is read-what-exists: use status, list, read and replies,
and do not post into an existing channel unless the task explicitly allows it.
No attachments, mentions, edits, bulk sends, chat deletion or deletion of
channels created outside this server.
Configuration
User-editable YAML at ~/.config/teams-mcp/config.yaml; see
config.example.yaml. Precedence:
environment variables > config.yaml > defaults. The file is validated with
zod and re-read when it changes (no restart needed).
node dist/cli.js settings path
node dist/cli.js settings get
node dist/cli.js settings set work_hours.start 08:30
node dist/cli.js settings set default_duration_min 45
node dist/cli.js settings set aliases.joel joel@example.com
node dist/cli.js settings validateInvalid values are refused before the file is written; writes are atomic (0600).
The same operations exist as the settings MCP tool.
Important keys: timezone (default America/Chicago), work_hours,
default_duration_min, aliases, invite_allowlist, blocked_times,
cache.{own_calendar_ttl_minutes,busy_ttl_minutes,directory_ttl_minutes},
max_results.* (mail 1–50, default 25 — the per-call top cap an operator
can raise; calendar 1–50; people 1–25; slots 1–20; preview_chars 40–1000,
default 300), snapshot_dir, test_event_prefix, and the safety block
(read_only, unsubscribe.{enabled,daily_cap}, write_rate_limit_per_minute).
The example file ships safety.read_only: true; the built-in default is false,
so a hand-written config without a safety block is write-enabled.
Paths:
Path | Purpose |
| user settings |
| dual-audience token cache (0600) |
| Teams-web Graph credential, own refresh lock (0600) |
| chats/channels this server created (0600) |
| persistent Chromium profile for silent re-auth |
| calendar snapshot (0600, safe to delete) |
| files saved by |
| append-only write journal (0600, rotates at 5 MB) |
| daily unsubscribe counter (0600) |
Environment overrides (see .env.example):
TEAMS_MCP_CONFIG_DIR, TEAMS_MCP_CONFIG_FILE, TEAMS_MCP_TIMEZONE,
TEAMS_MCP_PROFILE_DIR, TEAMS_MCP_CACHE_DIR, TEAMS_MCP_SNAPSHOT_DIR,
TEAMS_MCP_OUTLOOK_BASE_URL, TEAMS_MCP_GRAPH_BASE_URL, request/TTL knobs,
TEAMS_MCP_READ_ONLY, TEAMS_MCP_UNSUBSCRIBE_ENABLED,
TEAMS_MCP_UNSUBSCRIBE_DAILY_CAP, TEAMS_MCP_WRITE_RATE_LIMIT_PER_MINUTE.
Calendar snapshots
availability op=snapshot (and the optional resource
teams-mcp://calendar/snapshot) exposes the full YAML view — metadata, own
events and per-attendee busy blocks; it can be ~10 KB and is intended for bulk
planning. For a single scheduling question, availability.freebusy/suggest
return compact summaries and are cheaper. Freshness: own calendar 5 minutes,
other people's busy 30 minutes (configurable). There is no delta sync in this
tenant (405), so each refresh is a bounded calendarview + getSchedule poll;
freebusy/suggest refresh only when the snapshot is stale or its range does not
cover the request. Concurrent refreshes coalesce per process, temp names are
unique per writer, and the file is replaced atomically — a reader never sees a
partial document and the previous snapshot survives a failed write.
Development
The repo includes a GitHub Actions workflow (.github/workflows/ci.yml: Node 22,
npm ci, typecheck, test, build, no secrets). It is not running right now because
GitHub Actions is blocked at the account level by a billing issue, so no CI badge
is shown; the same steps pass locally on Node 22.
npm run dev # tsx src/index.ts
npm run typecheck
npm test # vitest, no network
npm run build
npm run smoke # spawns dist/index.js, initializes, lists tools/resources
node scripts/dev/measure-surface.mjs # bytes + bytes/4 estimates: tools/list, per-tool schema, 4 read probes
LIVE_WRITES=1 npm run live-writes # one-time real probe: 1 event, 1 self-email
TEAMS_MCP_LIVE_TEST=1 npx vitest run test/live-read.test.ts # read-only live controlsA few tests can read optional redacted fixture payloads from
docs/recon-artifacts/; that directory is not committed, so those tests skip.
live-writes drives the built server over stdio as an agent would: create →
update → get → guarded delete refusal → delete → list for one calendar event, one
email to yourself (search → mark unread → mark read → move to Archive), and a
read-only unsubscribe_preview. It reads token.json read-only and aborts if the
outlook token is stale rather than refreshing.
Security notes
Full threat model, credential permissions, incident response and rotation
guidance: SECURITY.md.
Every call runs as the signed-in user; there is no impersonation.
Capability scoping:
TEAMS_MCP_READ_ONLY=1refuses every mutating op before any request;unsubscribe_applyis opt-in (disabled by default) and needsconfirm:trueplus a matchingexpected_sender; one global 30/minute token bucket covers every write. See Safety modes.Destructive ops need ids from a prior read;
calendar update/delete/respondalso requireexpected_subjectand abort on mismatch.unsubscribe_applyacts on at most that message's own https/mailto targets. No bulk unsubscribe, no mail deletion, no mailbox rule changes.mail.send/draft/forward,mail.send_draft(re-checked against the live draft),mail.replywithreply_all,calendar.create/updateandavailabilityattendees resolve names through the directory, then reject recipients outsideinvite_allowlistwhen the list is non-empty; ambiguity is an error, never a pick.Every write attempt is journaled to
~/.cache/teams-mcp/write-audit.jsonl(ids/counts and outcome only; no bodies, no tokens).mail.attachments/mail.get_attachmentare reads (allowed in read-only mode, no write token). Downloaded files land under~/.cache/teams-mcp/attachments/(0700/0600) and are reported by path only — the server never opens or executes them.Tokens are never logged; API errors redact
Bearer ….token.json,teams-web-token.json,teams-state.json, the browser profile, snapshots, the attachment cache, the audit journal and the unsubscribe counter are owner-only (0600/0700).Teams follows the same gates as mail/calendar: read-only refuses
teams.send/teams.create/teams.deletebefore any request; send/create needconfirm:true; create is channel-only (never a chat); posting to a chat/channel this server did not create requires the exact target in the operator-ownedteams.allowed_targets(target_not_allowedotherwise); and delete is channel-only, needsexpected_name(name_mismatch) and only removes channels recorded inteams-state.json. Channel-message reads use the Teams-web Graph token because that is the only credential here withChannelMessage.Read.All; seedocs/auth.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Permissioned access to Outlook, OneDrive and Teams via the user's own Microsoft account
Manage Microsoft 365 email, calendar, contacts and inbox rules via the Graph API with OAuth 2.0.
Read email/chat conversations, messages, contacts and teams; draft, send and update threads.
Gmail, Outlook, Drive, OneDrive and calendars for AI agents. Many accounts, one endpoint, audit log.
Related MCP Servers
- 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 interaction with Outlook / Microsoft 365 calendar, allowing users to list events, get event details, find meeting times, and access calendar and profile information.121 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Outlook mail, calendar, and contacts via Microsoft Graph API with secure device code authentication.79 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage Microsoft Outlook Desktop (Classic) calendar and email through local COM automation, without Microsoft Graph or Entra registration.MIT