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:
- finds the LevelDB folder, or uses
--leveldb, - 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,
- reads the LevelDB files directly (tables and logs, including Snappy-compressed blocks), without a LevelDB engine,
- decodes the IndexedDB keys and the Blink and V8 values,
- maps the Teams schema: messages in
replychainsand 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_readerfor the same bytes (golden.py).internal/indexeddb/testdata: a synthetic IndexedDB written bygen/main.go, and the recordsccl_chromium_readerreads 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.