zaungast

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 was decided about the release date", "catch me up on a channel I muted", "what's my team been discussing 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 & macOS (new Teams / WebView2), Node.js ≥ 22.5. Both use the same Chromium/WebView2 store, so the reader is identical; the local database is auto-discovered on each, or point TEAMS_LEVELDB_DIR at it manually — 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"]
# The Teams database is auto-discovered, so no path is needed. To set or override it,
# delete the "#" below and point it at your …indexeddb.leveldb folder:
# env = { TEAMS_LEVELDB_DIR = "/full/path/to/https_teams.microsoft.com_0.indexeddb.leveldb" }

Claude Desktop / other clients

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

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

If you want to set or override a variable, use this form instead:

{
  "mcpServers": {
    "zaungast": {
      "command": "npx",
      "args": ["-y", "zaungast"],
      "env": {
        "TEAMS_LEVELDB_DIR": "/full/path/to/https_teams.microsoft.com_0.indexeddb.leveldb"
      }
    }
  }
}

TEAMS_LEVELDB_DIR is optional — the database is auto-discovered. Set it only if discovery fails or to pin a specific profile. 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_conversation | Browse one conversation's messages in story order (window / date-range / page back). | | read_thread | Read one channel reply-chain in full (root + all replies). | | get_message | One message in full — complete untruncated body + reactions, by conversation + m:<id>. | | search | Full-text search + filters (from, in, kind, mentions_me, has-attachment, date). | | list_events | Calendar meetings & appointments (forward window by default); metadata-only, join-URLs never exposed. | | list_calls | Call history — 1:1/group calls with direction, duration, missed, and recording pointers. | | rank_topics | Rank 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 | Absolute path to the …indexeddb.leveldb folder (examples below). Set only if auto-discovery fails, or to pin one profile when you have several. | | 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. | | ZAUNGAST_ENGINE | js | Ingest engine: js (built-in, zero-dep), native (require the optional libzaungast-native accelerator; errors if unavailable), or auto (native when available, else JS). See Configuration → Native engine. |

TEAMS_LEVELDB_DIR points at the folder ending in .indexeddb.leveldb (the one holding CURRENT, MANIFEST-*, *.ldb/*.log) — not its parent IndexedDB directory:

# Windows
C:\Users\<you>\AppData\Local\Packages\MSTeams_8wekyb3d8bbwe\LocalCache\Microsoft\MSTeams\EBWebView\<profile>\IndexedDB\https_teams.microsoft.com_0.indexeddb.leveldb

# macOS
/Users/<you>/Library/Containers/com.microsoft.teams2/Data/Library/Application Support/Microsoft/MSTeams/EBWebView/<profile>/IndexedDB/https_teams.microsoft.com_0.indexeddb.leveldb

<profile> is usually WV2Profile_tfw. Use the full absolute path in JSON configs (e.g. Claude Desktop) — environment placeholders like ~ or %LOCALAPPDATA% aren't expanded there.

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.