cd /news/ai-tools/teamscache-read-local-microsoft-team… · home › topics › ai-tools › article
[ARTICLE · art-174114] src=github.com ↗ pub= topic=ai-tools verified=true sentiment=· neutral

TeamsCache – Read Local Microsoft Teams Messages via CLI or MCP

A tool called teamscache, published by developer stn1slv, reads the local message cache of the new Microsoft Teams (v2) desktop client and outputs chats, messages and @-mentions as JSON, and can run as a read-only MCP server for AI assistants. The tool avoids Microsoft Graph, OAuth, Azure app registration and the network entirely, reading only what the signed-in Teams client already stores on disk, which the author says helps users such as guests in another company's tenant who often cannot obtain Graph permissions like Chat.Read without admin consent. It installs via Homebrew (brew install stn1slv/tap/teamscache), Go 1.27 or later, or make build, requires a new Teams client signed in at least once, and auto-discovers the cache on macOS and Windows but only best-effort on Linux.

key takeaway

teamscache exposes local Teams v2 cache data as JSON and as a read-only MCP server without Graph, OAuth or network access, with --limit 0 meaning no limit and the mcp command caching for 180s by default.

read7 min views2 publishedNov 22, 2026
TeamsCache – Read Local Microsoft Teams Messages via CLI or MCP
Image: Michielbdejong (auto-discovered)

teamscache reads the message cache of the new Microsoft Teams (v2) desktop client on your computer. It prints chats, messages and @-mentions as JSON, and it can also run as a read-only MCP server for AI assistants.

It does not use Microsoft Graph, OAuth, an Azure app registration or the network. It reads only what the signed-in Teams client already keeps on your disk.

To read Teams messages through Microsoft Graph, you need permissions such as Chat.Read, and many tenants allow them only after admin consent. As a guest in another company's tenant, you often cannot get that consent. The desktop client still keeps your recent conversations on your disk, and teamscache reads them from there.

With Homebrew on macOS or Linux:

brew install stn1slv/tap/teamscache

Binaries for macOS, Linux and Windows are on the releases page.

With Go 1.27 or later:

go install github.com/stn1slv/teamscache/cmd/teamscache@latest

Or build from source with make build; the binary is written to bin/teamscache.

You need a new Teams client that has been signed in at least once. Auto-discovery of the cache works on macOS and Windows. On Linux it is best effort.

Read all cached messages in one chat (oldest first):

teamscache conversations --limit 0       # find the conversation "id"
teamscache read "19:abc@thread.v2" --limit 0

Filter by account or WebView2 profile when you have multiple tenants or profiles:

teamscache accounts                      # get "<tenantId>:<userId>"
teamscache overview --account "<tenantId>:<userId>"

teamscache profiles                      # get profile folder name
teamscache overview --profile "Default"

Save JSON output to a file (JSON goes to stdout, summary goes to stderr):

teamscache read "19:abc@thread.v2" --limit 0 > chat.json

teamscache reads only messages stored in the local Teams desktop cache, not older history that Teams has not cached on disk. read returns messages oldest first; recent, search, mentions, and overview return newest first.

teamscache accounts                      # tenant and user contexts in the cache
teamscache profiles                      # discovered WebView2 cache profiles
teamscache overview --days 7             # recent activity grouped by conversation
teamscache recent --days 7               # messages of the last 7 days, newest first
teamscache mentions --unread             # @-mentions of you that are not read yet
teamscache search "quarterly budget"     # text in message content or sender name, newest first
teamscache conversations                 # chats and channels (id, title, type, last message)
teamscache read "19:abc@thread.v2"       # last 50 messages of one conversation, oldest first
teamscache dump                          # accounts, conversations, messages and mentions in one JSON object

All commands print JSON to stdout and a short summary to stderr, for example # 12 result(s), 0 record(s) skipped, 0 damaged section(s). Skipped records could not be decoded. Damaged sections are unreadable file sections or missing referenced blob files, and are counted separately.

Command Flags and defaults
conversations --limit 50
search QUERY --limit 50 ,--days 0
read CONVERSATION_ID --limit 50
recent --limit 200 ,--days 7
mentions --limit 100 ,--days 0 ,--unread (false )
overview --days 7
dump --days 0
mcp --cache-ttl 180s (Go duration, such as180s or3m )

In those command flags, --limit N sets the maximum number of results (0 means no limit). --days N keeps only items from the last N days (0 means all dates, and --limit still applies). --unread keeps only unread @-mentions.

Global flags:

Flag Meaning
--account <tenantId>:<userId> Only one account. The keys come from teamscache accounts . Withmcp , every tool serves only this account.
--leveldb PATH Read this cache folder instead of the auto-discovered one. Cannot be combined with --profile .
--profile NAME Choose a discovered WebView2 profile by folder name (see teamscache profiles ). Cannot be combined with--leveldb .
--max-content N Characters of message content in CLI mentions ,overview ,dump , and all MCP results (0 means no limit, default600 ). CLIconversations ,read ,recent , andsearch print full content.
-v ,--verbose Log details, such as skipped records, to stderr.

Environment variables:

Variable Meaning
TEAMSCACHE_LEVELDB Default for --leveldb (cannot be set withTEAMSCACHE_PROFILE ).
TEAMSCACHE_PROFILE Default for --profile (cannot be set withTEAMSCACHE_LEVELDB ).
TEAMSCACHE_MAX_CONTENT Default for --max-content .
TEAMSCACHE_CACHE_TTL Integer number of seconds the MCP server reuses a parsed cache (default 180 ).

The cache has no general read or unread marker. The read state of @-mentions is the only read state it keeps, so mentions --unread is the reliable way to find what needs your attention.

teamscache mcp runs a read-only MCP server on stdin and stdout. Example configuration for Claude Desktop or Claude Code:

{
  "mcpServers": {
    "teams": { "command": "teamscache", "args": ["mcp"] }
  }
}

Pass --max-content 0 for full message content in MCP tool results, or --account <tenantId>:<userId> to serve only one account:

{
  "mcpServers": {
    "teams": {
      "command": "teamscache",
      "args": ["mcp", "--max-content", "0", "--account", "<tenantId>:<userId>"]
    }
  }
}
Tool Purpose Key arguments and defaults
overview Who messaged you: recent activity grouped by conversation. A good first call. days (7 ),limit (100 ),account
recent_messages Messages of the last N days, newest first. days (7 ),limit (200 ),account
mentions @-mentions of you, with content and read state. days (0 ),unread_only (false ),limit (100 ),account
unread_messages Your unread @-mentions. days (30 ),limit (100 ),account
search_messages Text search in content and sender names. query (required),days (0 ),limit (50 ),account
list_conversations Chats and channels with their titles and IDs. limit (100 ),account
read_conversation Last messages of one conversation, oldest first. Pass limit: 0 for all cached messages. conversation_id (required),limit (50 ),account
list_accounts Accounts in the cache; use key as theaccount filter. none

The server parses the cache on the first tool call and keeps the result in memory. It parses again when the TTL ends or when Teams writes new data.

Every tool response keeps its rows in result and includes skipped_records, damaged_sections, and partial. When partial is true, some cache data could not be read, so an empty result does not confirm that no matching messages exist.

The new Teams client (com.microsoft.teams2 on macOS, the MSTeams package on Windows) is an Edge WebView2 app. It stores recent conversations in an IndexedDB database, which Chromium keeps in LevelDB with values in the V8 serialization format. teamscache:

  1. finds the LevelDB folder, or uses --leveldb ,
  2. copies its data files and referenced blob files to a temporary folder, because the running client locks the files, and removes the copy when it is done,
  3. reads the LevelDB files directly (tables and logs, including Snappy-compressed blocks), without a LevelDB engine,
  4. decodes the IndexedDB keys and the Blink and V8 values,
  5. maps the Teams schema: messages in replychains and its numbered copies such asreplychains-2 , chats inconversations , mentions inmentions-metadata-items , one database set per tenant and user.

LevelDB can keep older versions of a record until it compacts its files. teamscache uses only the newest version of each record, so an edited message shows its current text and the read state of a mention is the current one.

The LevelDB, IndexedDB and V8 decoding is a Go port of parts of ccl_chromium_reader. See THIRD_PARTY_NOTICES.md.

The tool is read-only and makes no network calls. The temporary copy of the cache is created with owner-only permissions and removed after each run. Output can contain message content from all tenants in the cache, so treat it as confidential.

make setup    # download dependencies
make test     # unit tests with the race detector
make lint     # golangci-lint and gofumpt
make format   # format the code
make build    # build bin/teamscache
make upgrade-deps # update dependencies and pinned Go tools

Tests use synthetic data only. The test fixtures and their generators are in testdata folders:

  • internal/v8/testdata : values written by Node.jsv8.serialize (gen.mjs ) and the result ofccl_chromium_reader for the same bytes (golden.py ).
  • internal/indexeddb/testdata : a synthetic IndexedDB written bygen/main.go , and the recordsccl_chromium_reader reads from it (gen/golden.py ).
  • internal/teams/testdata/gen : a synthetic Teams cache with edge cases, for manual end-to-end checks.

MIT. See LICENSE and THIRD_PARTY_NOTICES.md.

── more in #ai-tools 4 stories · sorted by recency
── more on @teamscache 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/teamscache-read-loca…] indexed:0 read:7min 2026-11-22 · —