msteams-personal-mcp

An MCP server for Microsoft Teams personal — the free/consumer Teams at teams.live.com that you sign in to with a personal Microsoft account (@outlook.com, @hotmail.com, @live.com, or any personal MSA).

It lets Claude, Cursor, VS Code and other MCP clients list your chats, read messages, find unread conversations, pull up what you sent recently and (when you ask) send messages.

Why this exists: Microsoft Graph's Teams chat APIs, Claude's Microsoft 365 connector, Microsoft's Work IQ MCP and the other community Teams MCP servers all require a work or school (Entra ID) account. None of them work with personal Teams. This one does.

Work/school Teams is not supported. Use a Graph-based server for that.

Contents

• Two ways to run it

• Option A: run locally (stdio)

• Option B: deploy your own remote server (Cloudflare, free)

• Connecting a client to a remote server

• Tools

• How sign-in and security work

• Limitations

• Troubleshooting

• Credits

Related MCP server: Teams Messenger MCP App

Two ways to run it

Option A: run locally (stdio)

Requirements: Node.js 18 or newer, and git.

git clone https://github.com/Vishnuhh/msteams-personal-mcp.git
cd msteams-personal-mcp
npm install

1. Sign in

node src/cli.js login

It prints a code. Open the link it shows (microsoft.com/devicelogin), enter the code and sign in with the account you use on teams.live.com. When the terminal prints "signedIn": true you're done. The sign-in is saved encrypted at %APPDATA%\teams-personal-mcp\ (Windows) or ~/.teams-personal-mcp/ (macOS/Linux) and refreshes automatically.

Check that it works:

node src/cli.js chats      # recent chats
node src/cli.js unread     # unread chats
node src/cli.js mine       # what you sent recently

2. Add it to your MCP client

Use the absolute path to src/index.js.

Claude Code

claude mcp add teams-personal -- node /absolute/path/to/msteams-personal-mcp/src/index.js

Claude Desktop (Settings → Developer → Edit Config → claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and most other clients:

{
  "mcpServers": {
    "teams-personal": {
      "command": "node",
      "args": ["/absolute/path/to/msteams-personal-mcp/src/index.js"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "teams-personal": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/msteams-personal-mcp/src/index.js"]
    }
  }
}

Restart the client. You can also sign in from inside the client: ask it to run teams_login.

3. (Optional) Wake Claude Code on new messages

With --listen, the local server is also a Claude Code channel. It checks Teams every 30 seconds and pushes new messages into your running session. It sends 1:1 messages, @mentions of you, and every message in the group chats you list. Your own messages are skipped. Each check is one request to Microsoft, plus one for each chat that has something new. Claude does no work until a message arrives.

claude mcp add teams-personal -e TEAMS_LISTEN_CHATS="19:abc@thread.v2,19:def@thread.v2" -- node /absolute/path/to/msteams-personal-mcp/src/index.js --listen
claude --dangerously-load-development-channels server:teams-personal

• TEAMS_LISTEN_CHATS: group chat ids to watch in full (get them with teams_find_chat). TEAMS_LISTEN_SECONDS: how often to check (default 30, minimum 15).

• The first start begins from now. Older messages are not replayed. Restarts don't send anything twice. After more than an hour offline, you get one "gap" notice instead of the backlog.

• Messages are untrusted text from other people. Keep teams_send_message, teams_reply_to_message, teams_edit_message and teams_delete_message on "ask" in your permissions, so nothing goes out to Teams without your OK.

• Channels are a Claude Code research preview. Custom channels need --dangerously-load-development-channels and an interactive session. On Team and Enterprise plans, an Owner must enable Channels first.

Option B: deploy your own remote server (Cloudflare, free)

This gives you one URL to share. Everyone who opens it signs in with their own personal Teams account and gets their own private MCP URL.

Why Cloudflare Workers: the free plan doesn't sleep (no cold-start timeouts), includes HTTPS and custom domains, and D1 stores sign-ins durably. The free plan currently allows 100,000 requests a day, which is plenty for a team.

Requirements: a free Cloudflare account, Node.js 22+ (Wrangler needs it), git.

1. Get the code

git clone https://github.com/Vishnuhh/msteams-personal-mcp.git
cd msteams-personal-mcp
npm install

2. Log in to Cloudflare

npx wrangler login

3. Create the database

npx wrangler d1 create msteams-personal-mcp

Copy the database_id it prints into wrangler.toml:

[[d1_databases]]
binding = "DB"
database_name = "msteams-personal-mcp"
database_id = "paste-the-id-here"

Then create the tables:

npm run db:migrate:remote

4. (Recommended) Set a private salt

This mixes a server-side secret into every user's encryption key. Set it before anyone signs in: changing it later invalidates every existing MCP URL.

npx wrangler secret put KEY_SALT

Paste a long random string when prompted (for example the output of openssl rand -base64 32).

5. Deploy

npm run deploy

Wrangler prints your URL, for example https://msteams-personal-mcp.<your-subdomain>.workers.dev. Open it in a browser and you should see the sign-in page.

6. (Optional) Use your own domain

Your domain must be managed by Cloudflare DNS. The free plan is fine:

1. In the Cloudflare dashboard, choose Add a domain and follow the steps to point your domain's nameservers at Cloudflare (done at your domain registrar). Wait until the domain shows as Active.

2. In wrangler.toml, uncomment and edit the route. Keep it near the top, above [vars]: in TOML, anything placed after a [section] header belongs to that section.

   routes = [
     { pattern = "teams-mcp.yourdomain.com", custom_domain = true }
   ]

3. Deploy again: npm run deploy. Cloudflare creates the DNS record and the HTTPS certificate automatically.

(Or in the dashboard: Workers & Pages → msteams-personal-mcp → Settings → Domains & Routes → Add → Custom domain.)

Also set REPO_URL in wrangler.toml to your repository so the sign-in page links to it.

7. Decide who can use it

Personal Microsoft accounts have no company domain, so the server decides access per account. Set ADMIN_USERNAME and ADMIN_PASSWORD (secrets, password at least 12 characters), open /admin, then Access:

• Your Teams account. Link it once (a sign-in code, like everyone else's). It always has access, and the Access page uses it to list your group chats. It is sealed under a key derived from KEY_SALT and ADMIN_PASSWORD, used only for that list, and changing the admin password unlinks it.

• Groups. Search your group chats and click Add (or paste a chat id, 19:…@thread.v2). Members get in automatically. Membership is checked with the person's own sign-in when they connect and again once a day, so leaving the group ends their access. Open a group to see who got in through it.

• Invites. For people outside your groups. Set how many uses and how many days, and add uses or days later; whoever signs in through the link keeps access until you remove them.

• Requests. Anyone else is refused, their Microsoft sign-in is not stored, and they appear here with Approve and Block (one at a time or in bulk). Connections that existed before access was restricted keep working and are listed under Under review until you approve or remove them.

Access is restricted by default once admin sign-in is set up; without it, the server is open to any personal Microsoft account. You can switch between Restricted and Open on the Access page.

8. (Optional) Server settings

Set these as Wrangler vars or secrets (npx wrangler secret put NAME). All are optional. The admin page (Settings) can override personal URLs, new-connection notes, the access code, the daily change cap, how long unused connections last and the alert webhook; its values win over the variables.

Connections unused for 90 days (or the number set in Settings) end automatically; a nightly job (cron in wrangler.toml) removes stale data.

Alert emails (free). The server can email the admin when a Cloudflare free-plan limit passes 80% or reaches 100% (checked hourly) and send a daily usage summary, as formatted HTML. It uses Cloudflare Email Routing, which is free on every plan for mail sent to your own verified address:

1. Cloudflare dashboard → your domain → Email Routing: turn it on (it replaces the domain's MX records) and add your address under Destination addresses; click the link Cloudflare emails you.

2. In wrangler.toml, add the binding and variables (an example is commented out there): [[send_email]] name = "ALERT_EMAIL" with destination_address = "you@example.com", plus ALERT_EMAIL_FROM (an address on that domain), ALERT_EMAIL_TO, PUBLIC_URL and optionally ALERT_TIMEZONE.

3. Deploy, then use Settings → Email alerts → Send test email. Both kinds can be switched off there.

Admin sign-in security. Sessions are stored on the server: they end after 30 minutes without use, after 8 hours, at sign-out, or when the admin password changes. Settings → Security turns on two-factor sign-in (any authenticator app), lists signed-in sessions and signs out everywhere else. Settings → Audit log lists every change made on the admin page for 180 days.

9. Share it

Send people the base URL, for example https://teams-mcp.yourdomain.com. Each person follows Connecting a client to a remote server.

Updating

git pull
npm install
npm run db:migrate:remote   # only if new migrations were added
npm run deploy

Test it locally first (optional)

npm run db:migrate:local
npm run dev:remote          # http://127.0.0.1:8787

Connecting a client to a remote server

There are two ways to connect. Sign in from your app (OAuth) is the easiest and keeps every key out of URLs; use a personal URL for clients that don't support MCP sign-in.

Option 1: sign in from your app (recommended)

Add the server's MCP address, https://teams-mcp.yourdomain.com/mcp, to your app. The app opens the server's sign-in page; press Get sign-in code, approve the code at microsoft.com/devicelogin with the personal Microsoft account you use on teams.live.com, and you are sent back to the app, connected.

Claude (claude.ai and the Claude desktop app): Settings → Connectors → Add custom connector. Name it Teams Personal, enter https://teams-mcp.yourdomain.com/mcp, Add, then Connect.

Claude Code

claude mcp add --scope user --transport http teams-personal https://teams-mcp.yourdomain.com/mcp

Then run /mcp inside Claude Code, pick teams-personal and choose Authenticate.

Cursor (~/.cursor/mcp.json); Cursor shows a Login button for the server:

{
  "mcpServers": {
    "teams-personal": { "url": "https://teams-mcp.yourdomain.com/mcp" }
  }
}

VS Code (.vscode/mcp.json); VS Code asks you to sign in when the server starts:

{
  "servers": {
    "teams-personal": { "type": "http", "url": "https://teams-mcp.yourdomain.com/mcp" }
  }
}

Behind the scenes this is standard MCP authorization (OAuth 2.1): discovery from the 401 response, dynamic client registration, authorization code with PKCE (S256). No client ID or secret to set up.

Option 2: a personal URL (any client)

1. Open the server's home page (for example https://teams-mcp.yourdomain.com).

2. Click Get sign-in code, approve it at microsoft.com/devicelogin.

3. Copy the personal MCP URL the page shows:

   https://teams-mcp.yourdomain.com/mcp/tpm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

   Treat this URL like a password. Anyone who has it can read and send your Teams messages. It is shown only once. If you lose it, sign in again to get a new one.

Use it anywhere an MCP URL goes, for example:

claude mcp add --scope user --transport http teams-personal https://teams-mcp.yourdomain.com/mcp/tpm_xxx

Clients that support headers can keep the key out of the URL: endpoint /mcp with Authorization: Bearer tpm_xxx. Clients that only support stdio can bridge with mcp-remote:

{
  "mcpServers": {
    "teams-personal": { "command": "npx", "args": ["-y", "mcp-remote", "https://teams-mcp.yourdomain.com/mcp"] }
  }
}

(mcp-remote handles the OAuth sign-in for you, so the plain /mcp address works.)

3. Try it

Ask your assistant things like:

• "Do I have unread Teams messages? Summarize what needs a reply."

• "Summarize the last 24 hours in the DevOps group."

• "Who is in the Design crew chat?"

• "React with a fitting emoji to Asha's last message."

• "Send 'Please review the PR' to DevOps and mention Ravi."

• "Mark the HR chat as read."

Revoking access

Ask your assistant to run teams_logout. That deletes your sign-in from the server and the connection (app sign-in or personal URL) stops working immediately. Removing the connector in your app also revokes it. You can also remove the app's access in your Microsoft account at account.live.com/consent/Manage.

Tools

Code mode (run_code)

For questions that need many reads ("which of my Squad chats mention the invoice since yesterday?"), Claude can run teams_query with action: "run_code": a short JavaScript program that calls the read actions (await teams.get_messages({ conversationId, since: "24h" })), filters and counts in the program, and returns only the answer. One step instead of many, and far less of Claude's context used.

• Read-only. Programs can't send, edit, delete or read files; changes still go through teams_do.

• Sealed. Programs run in QuickJS (WebAssembly) inside the server: no network, files, timers or secrets.

• Limited. Each run may make about 45 requests to Microsoft (15 ordinary reads, or one cross-chat search plus a few reads), compute for about 10 ms and last 25 seconds. Every read counts toward the person's normal limits.

• Free. It runs inside the same Worker on the Workers Free plan; no Dynamic Workers or paid plan.

Staying up to date without reconnecting

Apps (Claude, Cursor, VS Code) cache a server's tool list when they connect and don't reload it on their own. So the named tools above are kept stable, and new features arrive as actions behind teams_query (reading) and teams_do (changes): they work for every connected app the moment the server is updated.

• If an update ever changes the named tools, the server notices which connections still have the old list and adds a one-line note to Claude's answer asking the person to refresh the connector (Disconnect, then Connect).

• For developers: add new features with action(...) in src/core/tools.js, not reg(...). Changing a named tool means bumping TOOLS_VERSION (a test reminds you).

Prompts (one-click workflows)

Clients that support MCP prompts (Claude Code / menu, Claude desktop "+" menu, VS Code, …) also get:

How sign-in and security work

• Microsoft's standard device-code sign-in. You approve access on Microsoft's own page. This server never sees your password, and no Azure app registration is needed.

• Teams personal APIs. After sign-in, the server exchanges your token for a Teams session at teams.live.com and calls the same chat service the Teams web app uses.

• Files shared in chats live in the sender's OneDrive. To read one, the server gets a short-lived Microsoft Graph token from the same sign-in (Microsoft pre-approves the Teams app for this, so there is no extra consent screen) and downloads only the file you asked for, from a chat you are in. Microsoft issues this access as read-write to OneDrive; the tools only read files posted in your chats, and nothing is copied or kept on the server. Pasted pictures come from Skype's media service with your Teams session. Tokens are only ever sent to Microsoft's own hosts; OneDrive's download links are fetched without any token.

• PDFs on the free Cloudflare plan: a full PDF engine needs more CPU than a free request allows, so the remote server uses Cloudflare's free document converter (Workers AI toMarkdown, [ai] binding in wrangler.toml), then a small built-in reader, then the scanned page pictures. The local server reads PDFs with pdf.js (unpdf). Scans stored as fax-style strips can't be read on either; open them in Teams.

• Local mode: your refresh token is encrypted (AES-256-GCM) in your user profile with a machine- and user-bound key.

• Remote mode, per-user isolation:

  • Your personal URL contains a random 256-bit access key (tpm_…) that only you hold.

  • The database stores only SHA-256(access key) as your record id, plus your Microsoft refresh token encrypted with AES-256-GCM under a key derived (HKDF) from your access key and the server's KEY_SALT.

  • A database dump alone, or the person running the server, can't decrypt anyone's tokens without that user's URL.

  • Pending sign-in codes are sealed the same way and expire after 15 minutes.

  • To find chats quickly, the server keeps a list of your chats' ids and names in Cloudflare's cache (not the database), sealed the same way, for up to 30 days. Who the other person in each 1:1 chat is (their Teams id, and their display name when it came from their messages) is cached there too, not sealed, for 30 days.

  • Per-IP rate limits protect the public endpoints: 5 sign-in starts, 40 sign-in checks and 300 MCP requests per minute (Cloudflare rate-limit bindings in wrangler.toml).

  • Per-person limits: 120 requests a minute, 10 multi-chat searches a minute, 10 changes a minute and 200 changes a day. Microsoft "slow down" responses are retried once, then explained.

  • Each new connection posts a note to the person's own Teams Notes, connections end after 90 days unused, and teams_logout with everywhere=true ends all of an account's connections.

  • Access per account: members of chosen Teams groups (re-checked daily), invite links, or approval. Refused sign-ins are dropped before anything is stored. See "Decide who can use it" above.

• App sign-in (OAuth 2.1). The server is its own authorization server: discovery (RFC 9728 / RFC 8414), dynamic client registration (RFC 7591), authorization code with PKCE S256 only, single-use codes valid 10 minutes, exact redirect-URI matching, resource indicators (RFC 8707), iss in the redirect (RFC 9207) and token revocation (RFC 7009). The access token it issues is the same 256-bit per-user key, so the encryption above applies unchanged. The sign-in page names the requesting app and where you will be sent back, and cannot be framed.

• Tools are labelled read-only, changing or destructive (MCP annotations), so apps ask before changes, and message text is marked as content from other people, not instructions.

• Sending messages is a separate tool, described to the AI as "only when the user explicitly asked". Most clients also ask you to approve each tool call.

• Self-hosting is the most private option. Whoever runs a server controls its code. Only use a shared server run by someone you trust.

Limitations

• Undocumented APIs. Teams personal has no official API for chats. This project uses the endpoints the Teams web client uses. Microsoft can change them at any time, and using them may not be covered by Microsoft's terms of service. Use at your own risk.

• Personal accounts only. Work/school Teams isn't supported.

• Text messages. Read/send covers text and rich-text messages, @mentions and reactions. Files, images, calls and meetings aren't supported yet.

• Names. Names come from your contact list, with a fallback to names seen in the chat. Someone who isn't in your contacts and has never written in the chat may show as an id.

• Remote limits. Cloudflare's free plan caps outgoing requests per call. The multi-chat tools (teams_get_my_recent_messages, teams_get_unread, teams_search_messages, teams_get_mentions) therefore scan up to about 15–20 recent chats per call.

• Search scans recent history client-side (personal Teams has no search API we can use), so it finds messages from the last weeks rather than years back.

Troubleshooting

Development

Every release is listed in CHANGELOG.md, which the server also shows at /changelog. To start a release: npm run release -- <version> "summary", edit the drafted entry, npm test, commit and tag. Tests fail if the version has no finished changelog entry.

npm test                 # unit tests (node:test)
npm run dev:remote       # remote server on http://127.0.0.1:8787 (after npm run db:migrate:local)

CI runs the tests, starts the local server and bundles the Worker on every push.

Project layout

src/
  core/oauth.js      Microsoft device-code sign-in and Teams token exchange (Node + Workers)
  core/teams.js      Teams personal chat-service client
  core/tools.js      MCP tool definitions shared by both servers
  index.js           Local stdio MCP server
  listen.js          Local listener: new messages as Claude Code channel events (--listen)
  cli.js             Local CLI (login, chats, unread, mine, ...)
  auth.js, store.js  Local sign-in state and encrypted file store
  worker.js          Remote multi-user server (Cloudflare Worker)
  remote/crypto.js   Per-user envelope encryption (Web Crypto)
  remote/page.js     Sign-in web page
migrations/          D1 schema
test/                Unit tests
wrangler.toml        Cloudflare config

Credits

The Teams personal sign-in flow and endpoints were worked out from purple-teams by Eion Robb (GPLv3). No code was copied from it. This project is not affiliated with or endorsed by Microsoft.

License

MIT