zaungast

<img src="https://raw.githubusercontent.com/mbe24/zaungast/main/assets/logo.png" alt="zaungast logo: a hatted figure peeking over a fence with binoculars" width="150" align="right">

zaungast (German: someone who watches over the fence without joining in) is a read-only, offline MCP server for Teams — search chats, read conversations, surface trending topics, and find people straight from the local on-disk cache, with no Graph API, no cloud, and no credentials, and token-economical output for coding agents (Claude Code, Claude Desktop, …).

The new Teams client stores your chats in a local on-disk database; zaungast reads a copy of it directly and serves it over MCP, so your agent can pull in Teams context — "what did Anna say about the deploy", "catch me up on the platform channel", "what's my team on about this week" — without you copy-pasting, and without any cloud API.

• Local & offline — reads the on-disk Teams cache. No MS Graph API, no network calls.
• No credentials — nothing to log in to, no tokens, no permissions to grant.
• Read-only & safe — the Teams files are only ever read/copied, never written, locked, or modified. It cannot corrupt your Teams data.
• Token-economical — every tool returns compact, shaped output, never bulk dumps.
• Zero-config — auto-discovers the local Teams database; just register and go.

⚠️ Windows only (new Teams / WebView2), Node.js ≥ 22.5. Teams on macOS uses a different storage engine and isn't supported yet — see requirements. Not affiliated with or endorsed by Microsoft. It reads your own local data on your own machine.

Installation

npx -y zaungast fetches and runs the server, so registering it in your MCP client is the whole install. No environment variables are needed in the common case — the local Teams database is auto-discovered.

Claude Code

Normal case — the Teams database is auto-discovered, so no variables are needed:

claude mcp add zaungast -- npx -y zaungast

Add --scope user to make it available in every project. Verify with claude mcp list (expect zaungast … ✓ Connected), then open a new session.

Only if auto-discovery fails or you have multiple profiles, set TEAMS_LEVELDB_DIR explicitly (the -e flag goes before the --) — see finding the Teams database folder:

claude mcp add zaungast \
  -e TEAMS_LEVELDB_DIR="C:\Users\me\AppData\Local\Packages\MSTeams_8wekyb3d8bbwe\LocalCache\Microsoft\MSTeams\EBWebView\WV2Profile_tfw\IndexedDB\https_teams.microsoft.com_0.indexeddb.leveldb" \
  -- npx -y zaungast

Codex

Add to ~/.codex/config.toml (or run codex mcp add zaungast -- npx -y zaungast):

[mcp_servers.zaungast]
command = "npx"
args = ["-y", "zaungast"]

Claude Desktop / other clients

Add to your client's MCP config (claude_desktop_config.json, .mcp.json, …):

{
  "mcpServers": {
    "zaungast": { "command": "npx", "args": ["-y", "zaungast"] }
  }
}

From-source setup and other clients are covered in the installation docs.

Tools

Tool	What it does
list_conversations	Your Teams sidebar — newest conversations, or filter by kind/participant/title/time.
read_messages	One conversation's messages in story order (window / cursor / around a hit).
search	Full-text search + filters (from, in, kind, mentions_me, has-attachment, date).
top_topics	Distinctive/trending topics over a window, vs your baseline, with an example each.
find_person	Resolve a name/nickname to a canonical person + handle, with contact stats.
describe_schema	Recovery tool: propose a field mapping when a Teams update changes the DB layout.

Full reference: tools documentation.

Environment variables

All optional — zaungast works with no configuration. Pass them via your MCP client's env block (as above).

Var	Default	Notes
TEAMS_LEVELDB_DIR	auto-discovered	Path to the …\IndexedDB\https_teams.microsoft.com_0.indexeddb.leveldb directory. Set only if discovery fails or to pin a profile.
ZAUNGAST_INCREMENTAL	copy-reuse	Refresh mode: copy-reuse (faster) or reparse (simpler).
ZAUNGAST_DB_DIR	unset	Read a static copy of the database directly (offline analysis); skips discovery and live refresh.

Privacy & safety

• Stays local — no network calls; reads data already on your machine and serves it to your local agent over stdio.
• Cannot harm Teams — no code path writes to, locks, or memory-maps the Teams directory; only read-and-copy.
• Images/files are URL-only — chat images live in Teams' cloud behind auth; zaungast notes that an attachment exists but never fetches it and never handles credentials.

More in the privacy & safety docs.

Documentation

Full documentation — tools reference, how it works, configuration, privacy, troubleshooting, and development — lives at https://zaungast.readthedocs.io/.

License

Apache 2.0 © Mikael Beyene. Not affiliated with or endorsed by Microsoft. "Microsoft Teams" is a trademark of Microsoft Corporation; this project only reads your own local data.