chatwatch
chatwatch's MCP server lets an agent use your signed-in Teams web session to read, watch, send, and manage Teams chats.
List chats with title, id, preview, unread status, and settings.
Read the last 1–50 messages of a chat without marking it read.
Wait up to 60 seconds for new incoming messages in watched chats, using an event sequence number.
Send text and optional local files to a chat; the chat’s send mode determines whether it sends, drafts, or refuses.
Download pictures and files from specified messages to a new local folder.
List draft replies waiting for a person to send or discard them.
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., "@chatwatch read the latest messages in my project team chat"
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.
What it is
chatwatch runs on your own computer, as your user, with your Teams sign-in. Your agents work with your chats through MCP tools or push handlers, and every send passes the chat's send mode before anything reaches Teams.

The Teams tab, seen on chatwatch's local page (made-up chats).
Related MCP server: Teams MCP Server
Features
Pull (MCP): any MCP client (Claude Code, Codex, Cursor, …) gets tools to list chats, read messages, wait for new ones, fetch attachments and send.
Push (handlers): each new batch of messages in a chat goes to a command or URL you choose; its answer is sent back to the chat.
You stay in control: every chat has a send mode.
draft(the default) keeps what an agent writes on the local page until you send or discard it;autosends at once;offrefuses.Nothing is marked read by watching. New messages are read through Teams' own chat service API from inside the tab, so chats stay unread. Sending opens the chat, which marks it read (Teams does that; it cannot be avoided).
See Teams on the page. A live view of chatwatch's Chrome, also when it runs without a window: click, scroll and type in it to sign in again when Teams asks.
The Teams token never leaves the tab. It is used inside the page and is never returned to Python, printed or saved.
Requirements
Python 3.9 or later. chatwatch uses the standard library only, so there is nothing else to install.
Chrome, Chromium or Edge. If chatwatch does not find it, set
CHATWATCH_CHROMEto its executable.A Microsoft Teams account you can sign in to on the Teams web page.
For the pull tools, an MCP client such as Claude Code, Codex or Cursor.
Quick start
git clone https://github.com/xxxxDev/chatwatch.git chatwatch && cd chatwatch
pip install . # or run python3 -m chatwatch from this folder
# 1. Sign in to Teams once, in chatwatch's own Chrome profile
chatwatch browser --show # sign in, then close the window
# 2. Run the watcher (starts Chrome headless) and open the page
chatwatch serve
chatwatch open # prints http://127.0.0.1:8766/#key=...
# 3. Give your agent the tools
claude mcp add teams -- chatwatch mcpHow it fits together
flowchart LR
agent["Your agent<br/>Claude Code, Codex,<br/>any MCP client"]
handler["Your handler<br/>a command or URL"]
mcp["chatwatch mcp"]
serve["chatwatch serve"]
mode{"Send mode<br/>of the chat"}
page["Local page<br/>you send or discard"]
tab["Teams tab in<br/>chatwatch's Chrome"]
teams[("Microsoft Teams")]
agent -- "MCP tools" --> mcp
mcp -- "local API + key" --> serve
serve -- "new messages" --> handler
handler -- "reply" --> serve
serve -- "read through the chat API,<br/>never marks read" --> tab
serve -- "send" --> mode
mode -- "auto" --> tab
mode -- "draft" --> page
page -- "you approve" --> tab
mode -- "off" --> refused["refused"]
page -. "live view" .- tab
tab <--> teamsAn agent works with chats in one of two ways. Through MCP it asks for chats and messages and sends when it decides to. Through a handler each new batch of messages is pushed to it, and its answer is sent back. Either way, every send passes the chat's send mode before anything reaches Teams.
The page
chatwatch open prints the page's address with its key; open it in your browser. It refreshes itself every few seconds.
Pause / Resume (top): the emergency stop, see Push handlers.
Teams screen: see below.
Drafts: every reply waiting for you. Edit the text, then Send or Discard. A draft whose earlier send may have gone out asks you to tick I checked the chat first, so nothing is sent twice by mistake.
Chats: each chat Teams lists, with a dot when unread. Per chat: Watch (record its new messages and pass them on), Send (
draft,autooroff;autoasks you to confirm) and Handler (where its new messages are pushed; handlers come fromconfig.json).Recent: the last 30 events: new messages, sends, drafts, refusals and errors.


Teams screen
On the page, Show under Teams screen displays what the Teams tab shows. Start operating sends your clicks, scrolling and typing to it (on a phone, use the text box and the Enter, ⌫ and Tab buttons); Reload Teams reloads the tab. A send waits while you operate, and your input waits for a send in progress. Only the Teams tab (or the Microsoft sign-in page it goes to) is shown; there is no address bar.
MCP tools
Tool | What it does |
| Chats with title, id, preview, unread flag and their settings |
| Last n messages of a chat, without marking it read |
| New incoming messages after an event number, waiting up to 60 s |
| Text and files to a chat, under its send mode |
| Download the pictures and files of given messages |
| Replies waiting for you on the page |
teams_send_message answers with a status:
sent: it is in the chat.draft: waiting for you on the page.refused: sending is off for this chat.not_sent: nothing went out; trying again is safe.maybe_sent: send was pressed but the message was not seen; do not resend before someone checks the chat.
A chat is named by its title, a part of the title that matches only one chat, or its id.
Push handlers
Define handlers in ~/.chatwatch/config.json and pick one per chat on the page:
{
"handlers": {
"claude": {"command": ["claude", "-p", "--output-format", "text",
"Answer this Teams chat. The messages are JSON on stdin."]},
"my-bot": {"url": "http://127.0.0.1:9000/teams", "timeout": 300}
}
}A command gets the batch as JSON on stdin; a URL gets it POSTed:
{"chat_id": "19:...", "chat": "Alice", "kind": "OneOnOneChat", "send": "draft",
"messages": [{"mid": "...", "author": "Alice", "time": "...", "text": "Hi"}]}It answers with plain text (the reply) or JSON {"text": "...", "files": ["/abs/path"]}. An empty answer sends nothing. The reply follows the chat's send mode. In auto, a send that certainly did not go is tried again after 20 s, 60 s and 180 s, then kept as a draft; one that may have gone is kept as a draft marked for checking, never resent by itself.
Two bots answering each other on auto never stop. Keep bot chats on draft. Pause on the page is the emergency stop: nothing is read, queued handler work is skipped, and while paused every auto chat behaves as draft. A reply that comes back after its chat was paused, unwatched or given another handler waits as a draft.
Using it with an agent
With the MCP tools added, ask your agent in plain words, for example:
Check my Teams chats for anything new from Alice and draft a reply.
Wait for new Teams messages for the next 10 minutes and answer the questions about the shipping schedule.
The agent lists chats, reads, waits and sends with the tools above. On a draft chat its replies wait on the page; switch a chat to auto only when you trust what it sends there.
Starting, stopping and signing in again
chatwatch serveruns in the foreground; stop it with Ctrl+C. Chrome keeps running;chatwatch browser stopcloses it.When Teams signs you out, reading stops with
NO_TEAMS_TOKEN. Sign in again on the page's Teams screen, or close Chrome and runchatwatch browser --show.Settings, drafts and the sign-in stay in
~/.chatwatchacross restarts. Messages that arrived while chatwatch was stopped are passed on when it starts again (up to the last 20 per chat); those that arrived while it was paused are not, so no late automatic reply goes out after a pause.
Troubleshooting
Message | What to do |
| Start |
| Teams signed out: sign in again (above). |
| Set |
| Use the exact title or the chat id from |
| Someone left text in that chat's message box; clear it on the Teams screen. |
| Teams is still loading or its page changed; look at the Teams screen, then try again. |
| Nothing was sent; trying again is safe. |
| Look at the chat before sending again. |
| Your input on the Teams screen waited for a send; try again. |
Command line
chatwatch chats
chatwatch read "Alice" 10
chatwatch send "Alice" "Hello" ./report.pdf # sends now, whatever the mode: you are the person
chatwatch set "Alice" --watch on --send auto --handler claudeSettings
Variable | Default | |
|
| config, state, events, drafts, API key, Chrome profile |
|
| page and local API |
|
| DevTools port of chatwatch's Chrome |
| use a Chrome you already run with | |
| path to the Chrome executable | |
|
| seconds between checks |
|
| address of the running |
How it works
teams.py reads through the chat service API inside the Teams tab and sends by pasting the whole text into the compose box (a synthetic paste keeps line breaks; typing key by key now and then lost a key), attaching files through the file chooser, pressing send, and waiting for the message to appear. service.py polls, records events, runs handlers and applies send modes. http_api.py serves the page and the local API; mcp.py is a stdio MCP server that talks to that API. cdp.py is a small DevTools client.
Teams changes its web page from time to time; the selectors in teams.py then need updating.
Limits
Chats only, not channel posts.
Chats are found among those Teams lists in its sidebar.
Sending marks the chat read; watching does not.
It depends on the Teams web page. When Teams changes it, reading or sending can stop until
teams.pyis updated; the error names the step that failed.
Security
The page and API listen on 127.0.0.1 only and need the key in ~/.chatwatch/api-key. Agents read what other people write to you, and in an auto chat what they write goes out at once. Read SECURITY.md before connecting an agent, and use it to report a problem.
Contributing
See CONTRIBUTING.md before you open an issue or a pull request. Changes are listed in CHANGELOG.md and ideas for later in docs/ROADMAP.md.
License
The code is under the MIT License.
chatwatch is an independent project. It is not made by, affiliated with or endorsed by Microsoft. Microsoft Teams is a trademark of Microsoft.
Made by V-AX.
Available Tools
6 toolsteams_get_attachmentsA
Download the pictures and files of the given messages (mid values) of a chat into a new local folder; returns the paths.
Inputs: chat (required), message_ids (required).
teams_list_chatsA
List the Teams chats with their title, id, last message preview, unread flag and settings (watch, send mode off|draft|auto, handler). refresh=true reads the page again.
Inputs: refresh.
teams_list_draftsC
Replies waiting for a person to send or discard them on the chatwatch page.
Inputs: no named parameters.
teams_read_messagesA
Read the last n messages of a chat (title, title fragment or id) without marking it read.
Inputs: chat (required), n.
teams_send_messageA
Send text, and optionally local files (absolute paths), to a chat. The chat's send mode decides: auto sends now (status sent), draft saves it for a person to approve (status draft), off refuses. not_sent: nothing went out, you may try again. maybe_sent: do not resend; ask a person to check the chat. Sending opens the chat, which marks it read.
Inputs: chat (required), text (required), files.
teams_wait_for_messagesA
New incoming messages in watched chats after event number after_seq, waiting up to wait_seconds (max 60) for one. Without after_seq, only messages from now on. Returns events and seq: pass seq as after_seq next time. With chat, other chats' messages are skipped and the answer may be empty before wait_seconds.
Inputs: chat, after_seq, wait_seconds.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools target clearly different operations: listing chats, reading history, waiting for new events, sending, fetching attachments, and listing drafts. The closest pair is teams_read_messages vs teams_wait_for_messages, but the descriptions make the distinction (historical snapshot vs polling with after_seq/seq cursors) explicit enough that an agent can choose correctly.
Every tool uses the same teams_ prefix followed by a verb_noun snake_case pattern (list_chats, read_messages, send_message, get_attachments, list_drafts). No mixing of camelCase or inconsistent verb styles.
Six tools is well-scoped for a Teams chat bridge: one per lifecycle step (discover chats, read, poll, send, fetch attachments, review drafts) with no redundant entries. Nothing feels padded or missing at the count level.
Core read/poll/send/attachment/draft-listing flows are covered, but teams_list_chats exposes per-chat settings (watch, send mode, handler) with no tool to change them, and drafts can only be listed, never approved or discarded programmatically. Sending also opens/marks a chat read with no standalone mark-read/unread operation, forcing workarounds or human action on the chatwatch page.
Maintenance
Related MCP Connectors
Control your Chrome from chat: open websites, read what's on the page, click buttons, and fill in f…
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Messaging tools for AI agents: send messages, manage chats, groups and channels.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read conversations, send messages, and manage members in Microsoft Teams via the Teams Chat Service REST API.121 npm9MIT
- AlicenseNot gradedqualityBmaintenanceEnables LLM agents to read from and write to Microsoft Teams via a real browser-based bridge, with support for multi-tenant profiles, chat listing, message reading and searching, team/channel listing, and sending messages.MIT
- AlicenseAqualityCmaintenanceEnables Microsoft Teams chat automation, message extraction, and unread notification monitoring by automating the Teams web client with Puppeteer, requiring no API keys or Azure setup.512 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to interact with Microsoft Teams and Microsoft Graph, covering chats and channel messaging, message search, user and team member lookups, and file upload or attachment downloads. Supports OAuth device-code authentication, rich Markdown formatting, and LLM-friendly conversion of Teams HTML into Markdown.12 npmMIT