msteams-local-mcp
Read-only MCP access to locally cached Microsoft Teams v2 messages, chats, and mentions.
List signed-in Teams accounts/tenant-user contexts with inferred labels.
List chats/channels with IDs, titles, and types; optionally filter by account.
Read recent messages from a specific conversation, newest last.
Search cached messages by case-insensitive substring, optionally limited by recency.
Retrieve recent messages from the last N days in one call.
Find @-mentions of you, including content and read state; filter to unread only.
Get unread @-mentions as the cache’s reliable unread signal.
Summarize recent activity grouped by conversation, including counts, senders, and last message.
Scope most tools by account and control result limits/days; all operations are read-only and use local cache only.
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., "@msteams-local-mcp search my recent messages for 'quarterly budget'"
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.
msteams-local-mcp
Read the new Microsoft Teams (v2) message cache locally — and expose it over the Model Context Protocol (MCP) for AI assistants (Claude, etc.).
No Microsoft Graph. No OAuth. No Azure app registration. No network. It only reads what the signed-in Teams desktop client already keeps on your own disk.
Why
Reading your Teams messages through Microsoft Graph requires Chat.Read /
ChannelMessage.Read.All, which many tenants gate behind admin consent — so
if you're an external/guest member of a client's tenant, you often simply can't.
But the desktop client still caches your recent conversations locally, in the
clear, for the account you're signed into. This tool reads that cache.
Existing forensic parsers (e.g. forensicsim,
teams-decoder) target the older
Teams (classic / Teams 1.x) schema and return nothing on the current client.
msteams-local-mcp maps the current Teams 2.x schema (react-web-client:
replychain-manager → replychains → messageMap) on top of the excellent
ccl_chromium_reader for the
low-level Chromium LevelDB + V8 decoding. Nothing here is tied to any tenant or
account — it enumerates every context in the cache.
Related MCP server: msteams-mcp
How it works
The new Teams client (com.microsoft.teams2 on macOS, MSTeams MSIX on Windows)
is an Edge WebView2 app. It stores recent conversations in an IndexedDB database
backed by Chromium LevelDB, values serialized in V8. This tool:
locates that LevelDB (auto-discovery per OS, or
MSTEAMS_LEVELDB=/path),copies it to a temp dir (the running client holds a file lock),
enumerates each
(tenant, user)context and readsreplychains/conversations,yields plain-text messages (sender, timestamp, content), skipping the rare record that fails to deserialize.
Install
pipx install "git+https://github.com/KamorionLabs/msteams-local-mcp"
# or: uv tool install "git+https://github.com/KamorionLabs/msteams-local-mcp"Requires Python ≥ 3.10 and a signed-in new-Teams desktop client.
Use — CLI
msteams-local-dump accounts # tenant/user contexts + inferred label
msteams-local-dump conversations # chats/channels
msteams-local-dump search "quarterly budget" # substring search across messages
msteams-local-dump search "PR" --account <tenantId:userId> --limit 20Use — MCP
Run the server (stdio):
msteams-local-mcpRegister it with an MCP client. Example (Claude Desktop / Claude Code):
{
"mcpServers": {
"msteams-local": { "command": "msteams-local-mcp" }
}
}Tools exposed (all read-only):
Tool | Purpose |
| who messaged you: recent activity grouped by conversation (best first call) |
| messages received in the last N days, newest first — one call for "what did I miss" |
| @-mentions of you (with content + read state); |
| your unread @-mentions (the only reliable unread signal — see note) |
| substring search across messages, optional |
| messages of one conversation (newest last) |
| chats/channels (id, title, type); 1:1 and unnamed group chats use the title Teams shows |
| the tenant/user contexts, with an inferred org label |
All accept an optional account filter (a key from list_accounts) to scope to one
tenant/org. Note on unread: the local cache stores no general per-message read
marker, so true "all unread" can't be derived; unread_messages returns unread
@-mentions, and recent_messages covers "everything received while I was away".
Performance: the LevelDB is parsed once and cached (in memory + on disk, keyed on the store's signature), so chained calls are near-instant and re-parsing happens only when Teams writes new data or the snapshot format changes.
Scope, limits & ethics
Read-only. This tool never writes to Teams or sends anything.
Your own data. It reads the local cache of the account you are signed into. Use it only on machines and accounts you're authorized to. Respect your employer's / clients' policies and applicable law.
Recent only. The cache holds synced/recent conversations, not full history, and no server-side search.
Schema drift. Teams changes its internal schema between major versions; the mapping may need updates. PRs welcome.
Platforms: developed and tested on macOS (Teams 2.x, 2026). Windows paths are included; Windows testing/PRs welcome.
License
MIT — see LICENSE. Builds on ccl_chromium_reader (MIT).
Available Tools
8 toolslist_accountsA
List the Teams accounts (tenant/user contexts) in the local cache.
Each: key (use as the account filter elsewhere), tenant_id,
user_id and a best-effort label inferred from org names in messages.
Inputs: no named parameters. Returns: result
list_conversationsB
List chats/channels (id, title, type), optionally filtered by account.
Inputs: limit, account. Returns: result
mentionsA
@-mentions of you (someone @mentioned you), newest first, with content.
unread_only keeps only not-yet-read mentions; days restricts recency;
account scopes to one tenant (see list_accounts). This is the only
reliable read/unread signal in the local store.
Inputs: days, limit, account, unread_only. Returns: result
overviewA
Who messaged you: recent activity grouped by conversation, newest first.
Per conversation: title, message count, distinct senders, last message + time. Great first call to get the lay of the land before drilling in.
Inputs: days, account. Returns: result
read_conversationC
Return up to limit most recent messages of a conversation (newest last).
Inputs: conversation_id (required), limit, account. Returns: result
recent_messagesA
Messages received in the last days days, newest first — in ONE call.
Ideal for 'what did I get while I was away'. Filter by account (see
list_accounts) to scope to one tenant/org.
Inputs: days, limit, account. Returns: result
search_messagesB
Case-insensitive substring search across cached messages.
Optional days restricts to messages received in the last N days.
Inputs: query (required), days, limit, account. Returns: result
unread_messagesA
Unread items needing attention = your UNREAD @-mentions.
⚠️ The local Teams cache has NO general read marker (per-message read state is
not stored on disk), so true 'all unread' can't be derived. Unread @-mentions
are the reliable signal. For 'everything that arrived while I was away', use
recent_messages(days=...) instead (you read nothing while away → recent ≈ unread).
Inputs: days, limit, account. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools are distinct, but mentions and unread_messages overlap significantly — both describe '@-mentions' and read/unread state. The descriptions try to disambiguate (unread_messages explicitly warns it's just unread @-mentions), but an agent could easily misselect between them or between recent_messages and read_conversation.
The naming follows a verb_noun pattern (list_accounts, list_conversations, read_conversation, search_messages). However 'recent_messages', 'mentions', and 'overview' break the pattern by being noun-phrases rather than verb_noun. Also verb choice is inconsistent — 'list', 'read', 'search', 'recent', 'mentions', 'overview'. Mix of verb-led and noun-led names.
8 tools is a reasonable, well-scoped count for a Teams-cache read-only server. There are no redundant padding tools. Could arguably be condensed (mentions + unread_messages overlap), but 8 is within a comfortable range.
The server is read-only covering account listing, conversation listing/reading, searching, recency, mentions/unread, and overview. However there are notable gaps: no way to fetch a single specific message by ID, no filter by sender, no pagination beyond simple 'limit', and no ability to drill into unread across all conversation types beyond mentions. The surface is functional for typical 'what happened' queries but lacks finer-grained access.
Maintenance
Related MCP Connectors
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Hosted WhatsApp MCP server: read, search and reply to your own WhatsApp chats from your AI.
Read-only MCP server exposing a user ORANO library to their own AI agent.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Related MCP Servers
- AlicenseAqualityCmaintenanceA read-only, offline MCP server for Microsoft Teams that searches chats, reads conversations, and finds people directly from the local on-disk cache with no cloud API.63Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP server for Microsoft Teams that lets AI assistants search, message, and manage chats, meetings, files, and contacts using your existing Teams browser login—no app approval or Azure AD registration needed.2,781 npm3MIT
- AlicenseBqualityDmaintenanceProvides read-only access to Telegram chats, allowing AI agents to list chats, read messages, and search within chats via local MCP.14MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI clients to read and search macOS Messages history through a read-only MCP interface.-