msgraph-mcp-server 0.3.0__tar.gz → 0.3.2__tar.gz

{msgraph_mcp_server-0.3.0 → msgraph_mcp_server-0.3.2}/.env.example

@@ -2,4 +2,3 @@ MSGRAPH_MCP_CLIENT_ID=
 MSGRAPH_MCP_TENANT_ID=
 # Optional: override token cache location (default ~/.msgraph-mcp/token_cache.bin)
 # MSGRAPH_MCP_TOKEN_CACHE_PATH=
-# Legacy OUTLOOK_MCP_* names are still honored as a fallback.

msgraph_mcp_server-0.3.2/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python-dependencies:
+        patterns: ["*"]
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      github-actions:
+        patterns: ["*"]

msgraph_mcp_server-0.3.2/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} --group dev pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Type check
+        run: uv run pyright src tests

msgraph_mcp_server-0.3.2/.github/workflows/release.yml

@@ -0,0 +1,112 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  # Publishing to PyPI is irreversible (a version can be yanked, never reused),
+  # so the full check suite gates the release.
+  verify:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} --group dev pytest -q
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Type check
+        run: uv run pyright src tests
+
+  build:
+    needs: verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check tag matches package version
+        run: |
+          version=$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject.toml version $version" >&2
+            exit 1
+          fi
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  mcp-registry:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # required for MCP registry OIDC login
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Set version in server.json from tag
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          jq --arg v "$VERSION" '.version = $v | .packages[0].version = $v' server.json > server.tmp && mv server.tmp server.json
+
+      - name: Wait for package on PyPI
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          for i in $(seq 1 30); do
+            if curl -sf "https://pypi.org/pypi/msgraph-mcp-server/$VERSION/json" > /dev/null; then
+              echo "PyPI has $VERSION"
+              exit 0
+            fi
+            echo "waiting for PyPI ($i)..."
+            sleep 10
+          done
+          echo "Timed out waiting for msgraph-mcp-server $VERSION on PyPI" >&2
+          exit 1
+
+      - name: Authenticate to MCP registry
+        run: ./mcp-publisher login github-oidc
+
+      - name: Publish to MCP registry
+        run: ./mcp-publisher publish

msgraph_mcp_server-0.3.2/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/timfurlong/msgraph-mcp
+cd msgraph-mcp
+uv sync
+cp .env.example .env   # fill in MSGRAPH_MCP_CLIENT_ID and MSGRAPH_MCP_TENANT_ID
+uv run msgraph-mcp-login
+```
+
+Point an MCP host at the working tree with:
+
+```bash
+claude mcp add msgraph -- uv --directory "$(pwd)" run msgraph-mcp
+```
+
+## Checks
+
+CI runs all four on every push and pull request, against Python 3.11, 3.12, and 3.13.
+
+```bash
+uv run pytest                            # unit tests
+uv run ruff check .                      # lint
+uv run ruff format .                     # format (CI runs --check)
+uv run pyright src tests                 # types, must stay at zero errors
+```
+
+Integration tests make real Graph calls against the signed-in account and are skipped unless you opt in:
+
+```bash
+MSGRAPH_MCP_INTEGRATION=1 uv run pytest
+```
+
+## Releasing
+
+Releases are tag-driven. Bump `version` in `pyproject.toml`, commit, then:
+
+```bash
+git tag vX.Y.Z && git push origin vX.Y.Z
+```
+
+The tag must match the `pyproject.toml` version or the workflow fails. From there
+`.github/workflows/release.yml` runs the checks, publishes to PyPI via Trusted
+Publishing (OIDC, no API tokens), and updates the MCP registry entry from
+`server.json`.
+
+Two things to know:
+
+- PyPI versions can be yanked but never reused, so a bad release costs a version number.
+- The README is the PyPI long description and the registry's ownership proof. It must
+  keep the `mcp-name: io.github.timfurlong/msgraph-mcp` comment, and README changes only
+  reach PyPI and the registry when a new version ships.

msgraph_mcp_server-0.3.2/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: msgraph-mcp-server
+Version: 0.3.2
+Summary: MCP server for Microsoft Graph: Outlook mail and calendar, plus read-only Microsoft Teams
+Project-URL: Homepage, https://github.com/timfurlong/msgraph-mcp
+Project-URL: Repository, https://github.com/timfurlong/msgraph-mcp
+Project-URL: Issues, https://github.com/timfurlong/msgraph-mcp/issues
+Author: Tim Furlong
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calendar,email,mcp,microsoft-graph,model-context-protocol,outlook,teams
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0
+Requires-Dist: msal>=1.31
+Requires-Dist: msgraph-sdk>=1.0
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+# MSGraph MCP
+
+<!-- mcp-name: io.github.timfurlong/msgraph-mcp -->
+
+[![PyPI](https://img.shields.io/pypi/v/msgraph-mcp-server)](https://pypi.org/project/msgraph-mcp-server/)
+[![Python versions](https://img.shields.io/pypi/pyversions/msgraph-mcp-server)](https://pypi.org/project/msgraph-mcp-server/)
+[![CI](https://github.com/timfurlong/msgraph-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/timfurlong/msgraph-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/timfurlong/msgraph-mcp/blob/main/LICENSE)
+
+A Model Context Protocol (MCP) server for **Microsoft Graph**. It exposes Microsoft Outlook **mail** and **calendar**, plus read-only Microsoft **Teams** message history, to AI agents via the Microsoft Graph SDK. It acts as the signed-in user, using delegated permissions and MSAL device code flow, so it can only reach what that user can reach.
+
+## Install
+
+You need Python ≥ 3.11 and an Entra (Azure AD) app registration. The app registration takes about ten minutes and may need an administrator, so do that first: see the Entra setup section below.
+
+```bash
+uv tool install msgraph-mcp-server   # or: pip install msgraph-mcp-server
+```
+
+The package is `msgraph-mcp-server`. It installs three commands: `msgraph-mcp` and its alias `msgraph-mcp-server`, which both start the stdio server, plus `msgraph-mcp-login` for the one-time sign-in.
+
+## Setup
+
+**1. Set your Entra app credentials.**
+
+```bash
+export MSGRAPH_MCP_CLIENT_ID=<your app's client ID>
+export MSGRAPH_MCP_TENANT_ID=<your tenant ID>   # or: common / organizations / consumers
+```
+
+**2. Sign in once.** This prints a URL and a code; visit the URL and enter the code. No client secret is involved or stored.
+
+```bash
+msgraph-mcp-login
+# running via uvx instead of installing: uvx --from msgraph-mcp-server msgraph-mcp-login
+```
+
+A token cache is written to `~/.msgraph-mcp/token_cache.bin`.
+
+**3. Wire the server into your MCP host.**
+
+Claude Code:
+
+```bash
+claude mcp add msgraph \
+  --env MSGRAPH_MCP_CLIENT_ID=$MSGRAPH_MCP_CLIENT_ID \
+  --env MSGRAPH_MCP_TENANT_ID=$MSGRAPH_MCP_TENANT_ID \
+  -- msgraph-mcp
+```
+
+Any other host, over stdio:
+
+```json
+{
+  "mcpServers": {
+    "msgraph": {
+      "command": "msgraph-mcp",
+      "args": [],
+      "env": {
+        "MSGRAPH_MCP_CLIENT_ID": "<your app's client ID>",
+        "MSGRAPH_MCP_TENANT_ID": "<your tenant ID>"
+      }
+    }
+  }
+}
+```
+
+To run without installing, use `"command": "uvx"` with `"args": ["msgraph-mcp-server"]`. Note that `uvx` does not put `msgraph-mcp-login` on your `PATH`, so sign in with the `uvx --from` form shown in step 2.
+
+`MSGRAPH_MCP_TOKEN_CACHE_PATH` optionally overrides the cache location. All three variables can also come from a `.env` file in the working directory; the process environment wins over it.
+
+## Entra setup
+
+The app registration requires:
+
+- **Account type:** single tenant (multi-tenant works too; set `MSGRAPH_MCP_TENANT_ID` to `common`, `organizations`, or `consumers`)
+- **Redirect URI (public client):** `https://login.microsoftonline.com/common/oauth2/nativeclient`
+- **Allow public client flows:** Yes, under Authentication → Advanced settings. Device code flow fails without it.
+- **Delegated permissions** (Microsoft Graph):
+  - Mail: `Mail.ReadWrite`, `Mail.ReadWrite.Shared`, `Mail.Send`
+  - Rules: `MailboxSettings.ReadWrite` (Graph requires this for the `messageRules` endpoints)
+  - Calendar: `Calendars.ReadWrite`, `Calendars.ReadWrite.Shared`
+  - Identity: `User.Read`
+  - Teams: `Chat.Read`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Read.All`
+
+`ChannelMessage.Read.All` always needs tenant admin consent, and the `*.Shared` permissions may need it depending on your tenant.
+
+> **The scope list is all-or-nothing.** Sign-in requests every scope at once, so without admin consent for `ChannelMessage.Read.All` the login fails outright and mail and calendar are unavailable too. For the same reason, adding scopes later means re-running `msgraph-mcp-login`; until you do, *every* tool fails with `NotAuthenticatedError`, not just the ones needing the new scope.
+
+## Tools
+
+| Group          | Tools                                                                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Util           | `whoami`                                                                                                                                               |
+| Mail — read    | `list_messages`, `search_messages`, `get_message`, `list_attachments`, `download_attachment`                                                           |
+| Mail — write   | `send_message`, `create_draft`, `reply_message`, `reply_all_message`, `forward_message`, `update_message`, `delete_message`                            |
+| Mail — folders | `list_folders`, `create_folder`, `update_folder`, `delete_folder`, `move_message`                                                                      |
+| Mail — actions | `archive_message`, `mark_read`, `mark_unread`, `flag_message`, `unflag_message`                                                                        |
+| Mail — batch   | `batch_archive_messages`, `batch_move_messages`, `batch_mark_read`, `batch_mark_unread`, `batch_flag_messages`, `batch_unflag_messages`                |
+| Mail — rules   | `list_rules`, `get_rule`, `create_rule`, `update_rule`, `delete_rule`                                                                                  |
+| Calendar       | `list_calendars`, `list_events`, `get_event`, `create_event`, `update_event`, `delete_event`, `cancel_event`, `respond_to_event`, `find_meeting_times` |
+| Teams (read)   | `list_chats`, `list_chat_messages`, `list_joined_teams`, `list_channels`, `list_channel_messages`, `list_message_replies`, `download_hosted_content`      |
+
+Behavior shared across tools:
+
+- **Trimmed responses.** Results are reshaped for agents, and message and event bodies are replaced by a short `snippet`. Pass `include_body=true` to `get_message`, `list_chat_messages`, `list_channel_messages`, or `list_message_replies` for the full body, which for Teams is also what surfaces Adaptive Card content. Pass `include_raw=true` to any tool returning a Graph object to get the full payload alongside the trimmed one; the `batch_*` tools return per-message status only and do not accept it.
+- **Other mailboxes.** Every mail and calendar tool takes an optional `mailbox` (email or user ID) to target a shared or delegated mailbox. Omit it for your own. Teams tools are read-only, cover only your own chats, and take no `mailbox`.
+- **Pagination.** List and search tools take `limit` (1-100, default 25) and `page_token`, except `list_channel_messages` and `list_message_replies`, which Graph caps at 50. `list_folders`, `list_rules`, `list_attachments`, and `list_calendars` return the whole collection and take neither. On `list_joined_teams` and `list_channels`, `limit` is applied after fetching because Graph rejects `$top` there, so it saves tokens rather than round-trips.
+- **Batch actions.** The `batch_*` tools apply one action to up to 1000 messages via Graph's `$batch` endpoint, returning a per-message result plus a `{total, succeeded, failed}` summary.
+- **Downloads.** `download_attachment` and `download_hosted_content` return images as native MCP image blocks the agent can view. Pass `save_path` (a file, or an existing directory) to write bytes to disk and get back a path instead.
+- **Finding mail.** `list_messages` defaults to the inbox; pass `folder_id` for another folder, `unread_only=true`, or a raw OData `filter` for predicates KQL cannot express. `search_messages` passes your query to Graph's `$search` as KQL.
+
+Outgoing attachments are capped at 3 MB total per message; chunked upload is not supported. SharePoint-backed Teams file attachments cannot be downloaded, only inline hosted content.
+
+## Security
+
+The token cache holds your **refresh token**, which can mint access tokens for your mail, calendar, and Teams data. Treat the file as a credential. It lives at `~/.msgraph-mcp/token_cache.bin` with mode `0600` inside a `0700` directory.
+
+To revoke access, or to switch accounts, delete the cache and sign in again:
+
+```bash
+rm -f ~/.msgraph-mcp/token_cache.bin ~/.outlook-mcp/token_cache.bin
+```
+
+The second path matters if you ever ran this server under its former name `outlook-mcp`: that cache is still used as a fallback when the current one is absent, so deleting only the first file leaves a working refresh token on disk. To revoke fully, also remove the app at https://account.microsoft.com or in your organization's identity portal.
+
+## Troubleshooting
+
+- **`NotAuthenticatedError: Not authenticated`** — run `msgraph-mcp-login`. If it recurs immediately, a requested scope has not been consented yet; see the note under Entra setup.
+- **`ConfigError: Missing required env var`** — set it in your shell, in a `.env` in the working directory, or in your MCP host's env config.
+- **`Graph API 403: ErrorAccessDenied`** — the Entra app is missing a delegated permission, or it needs admin consent. Check the list above, then re-consent and sign in again.
+- **`Graph API 400: BadRequest — Syntax error`** from `search_messages` — the query goes to Graph's `$search` as KQL. Quote literal phrases (`"weekly report"`) or use fielded forms (`from:alice`). For predicates KQL cannot express, use `list_messages` with `filter=`.
+- **The host starts the server but lists no tools** — confirm it launches `msgraph-mcp` (or `uvx`) over stdio and can find that binary on its `PATH`.
+
+## Development
+
+See [CONTRIBUTING.md](https://github.com/timfurlong/msgraph-mcp/blob/main/CONTRIBUTING.md).

msgraph_mcp_server-0.3.2/README.md

@@ -0,0 +1,137 @@
+# MSGraph MCP
+
+<!-- mcp-name: io.github.timfurlong/msgraph-mcp -->
+
+[![PyPI](https://img.shields.io/pypi/v/msgraph-mcp-server)](https://pypi.org/project/msgraph-mcp-server/)
+[![Python versions](https://img.shields.io/pypi/pyversions/msgraph-mcp-server)](https://pypi.org/project/msgraph-mcp-server/)
+[![CI](https://github.com/timfurlong/msgraph-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/timfurlong/msgraph-mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/timfurlong/msgraph-mcp/blob/main/LICENSE)
+
+A Model Context Protocol (MCP) server for **Microsoft Graph**. It exposes Microsoft Outlook **mail** and **calendar**, plus read-only Microsoft **Teams** message history, to AI agents via the Microsoft Graph SDK. It acts as the signed-in user, using delegated permissions and MSAL device code flow, so it can only reach what that user can reach.
+
+## Install
+
+You need Python ≥ 3.11 and an Entra (Azure AD) app registration. The app registration takes about ten minutes and may need an administrator, so do that first: see the Entra setup section below.
+
+```bash
+uv tool install msgraph-mcp-server   # or: pip install msgraph-mcp-server
+```
+
+The package is `msgraph-mcp-server`. It installs three commands: `msgraph-mcp` and its alias `msgraph-mcp-server`, which both start the stdio server, plus `msgraph-mcp-login` for the one-time sign-in.
+
+## Setup
+
+**1. Set your Entra app credentials.**
+
+```bash
+export MSGRAPH_MCP_CLIENT_ID=<your app's client ID>
+export MSGRAPH_MCP_TENANT_ID=<your tenant ID>   # or: common / organizations / consumers
+```
+
+**2. Sign in once.** This prints a URL and a code; visit the URL and enter the code. No client secret is involved or stored.
+
+```bash
+msgraph-mcp-login
+# running via uvx instead of installing: uvx --from msgraph-mcp-server msgraph-mcp-login
+```
+
+A token cache is written to `~/.msgraph-mcp/token_cache.bin`.
+
+**3. Wire the server into your MCP host.**
+
+Claude Code:
+
+```bash
+claude mcp add msgraph \
+  --env MSGRAPH_MCP_CLIENT_ID=$MSGRAPH_MCP_CLIENT_ID \
+  --env MSGRAPH_MCP_TENANT_ID=$MSGRAPH_MCP_TENANT_ID \
+  -- msgraph-mcp
+```
+
+Any other host, over stdio:
+
+```json
+{
+  "mcpServers": {
+    "msgraph": {
+      "command": "msgraph-mcp",
+      "args": [],
+      "env": {
+        "MSGRAPH_MCP_CLIENT_ID": "<your app's client ID>",
+        "MSGRAPH_MCP_TENANT_ID": "<your tenant ID>"
+      }
+    }
+  }
+}
+```
+
+To run without installing, use `"command": "uvx"` with `"args": ["msgraph-mcp-server"]`. Note that `uvx` does not put `msgraph-mcp-login` on your `PATH`, so sign in with the `uvx --from` form shown in step 2.
+
+`MSGRAPH_MCP_TOKEN_CACHE_PATH` optionally overrides the cache location. All three variables can also come from a `.env` file in the working directory; the process environment wins over it.
+
+## Entra setup
+
+The app registration requires:
+
+- **Account type:** single tenant (multi-tenant works too; set `MSGRAPH_MCP_TENANT_ID` to `common`, `organizations`, or `consumers`)
+- **Redirect URI (public client):** `https://login.microsoftonline.com/common/oauth2/nativeclient`
+- **Allow public client flows:** Yes, under Authentication → Advanced settings. Device code flow fails without it.
+- **Delegated permissions** (Microsoft Graph):
+  - Mail: `Mail.ReadWrite`, `Mail.ReadWrite.Shared`, `Mail.Send`
+  - Rules: `MailboxSettings.ReadWrite` (Graph requires this for the `messageRules` endpoints)
+  - Calendar: `Calendars.ReadWrite`, `Calendars.ReadWrite.Shared`
+  - Identity: `User.Read`
+  - Teams: `Chat.Read`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Read.All`
+
+`ChannelMessage.Read.All` always needs tenant admin consent, and the `*.Shared` permissions may need it depending on your tenant.
+
+> **The scope list is all-or-nothing.** Sign-in requests every scope at once, so without admin consent for `ChannelMessage.Read.All` the login fails outright and mail and calendar are unavailable too. For the same reason, adding scopes later means re-running `msgraph-mcp-login`; until you do, *every* tool fails with `NotAuthenticatedError`, not just the ones needing the new scope.
+
+## Tools
+
+| Group          | Tools                                                                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Util           | `whoami`                                                                                                                                               |
+| Mail — read    | `list_messages`, `search_messages`, `get_message`, `list_attachments`, `download_attachment`                                                           |
+| Mail — write   | `send_message`, `create_draft`, `reply_message`, `reply_all_message`, `forward_message`, `update_message`, `delete_message`                            |
+| Mail — folders | `list_folders`, `create_folder`, `update_folder`, `delete_folder`, `move_message`                                                                      |
+| Mail — actions | `archive_message`, `mark_read`, `mark_unread`, `flag_message`, `unflag_message`                                                                        |
+| Mail — batch   | `batch_archive_messages`, `batch_move_messages`, `batch_mark_read`, `batch_mark_unread`, `batch_flag_messages`, `batch_unflag_messages`                |
+| Mail — rules   | `list_rules`, `get_rule`, `create_rule`, `update_rule`, `delete_rule`                                                                                  |
+| Calendar       | `list_calendars`, `list_events`, `get_event`, `create_event`, `update_event`, `delete_event`, `cancel_event`, `respond_to_event`, `find_meeting_times` |
+| Teams (read)   | `list_chats`, `list_chat_messages`, `list_joined_teams`, `list_channels`, `list_channel_messages`, `list_message_replies`, `download_hosted_content`      |
+
+Behavior shared across tools:
+
+- **Trimmed responses.** Results are reshaped for agents, and message and event bodies are replaced by a short `snippet`. Pass `include_body=true` to `get_message`, `list_chat_messages`, `list_channel_messages`, or `list_message_replies` for the full body, which for Teams is also what surfaces Adaptive Card content. Pass `include_raw=true` to any tool returning a Graph object to get the full payload alongside the trimmed one; the `batch_*` tools return per-message status only and do not accept it.
+- **Other mailboxes.** Every mail and calendar tool takes an optional `mailbox` (email or user ID) to target a shared or delegated mailbox. Omit it for your own. Teams tools are read-only, cover only your own chats, and take no `mailbox`.
+- **Pagination.** List and search tools take `limit` (1-100, default 25) and `page_token`, except `list_channel_messages` and `list_message_replies`, which Graph caps at 50. `list_folders`, `list_rules`, `list_attachments`, and `list_calendars` return the whole collection and take neither. On `list_joined_teams` and `list_channels`, `limit` is applied after fetching because Graph rejects `$top` there, so it saves tokens rather than round-trips.
+- **Batch actions.** The `batch_*` tools apply one action to up to 1000 messages via Graph's `$batch` endpoint, returning a per-message result plus a `{total, succeeded, failed}` summary.
+- **Downloads.** `download_attachment` and `download_hosted_content` return images as native MCP image blocks the agent can view. Pass `save_path` (a file, or an existing directory) to write bytes to disk and get back a path instead.
+- **Finding mail.** `list_messages` defaults to the inbox; pass `folder_id` for another folder, `unread_only=true`, or a raw OData `filter` for predicates KQL cannot express. `search_messages` passes your query to Graph's `$search` as KQL.
+
+Outgoing attachments are capped at 3 MB total per message; chunked upload is not supported. SharePoint-backed Teams file attachments cannot be downloaded, only inline hosted content.
+
+## Security
+
+The token cache holds your **refresh token**, which can mint access tokens for your mail, calendar, and Teams data. Treat the file as a credential. It lives at `~/.msgraph-mcp/token_cache.bin` with mode `0600` inside a `0700` directory.
+
+To revoke access, or to switch accounts, delete the cache and sign in again:
+
+```bash
+rm -f ~/.msgraph-mcp/token_cache.bin ~/.outlook-mcp/token_cache.bin
+```
+
+The second path matters if you ever ran this server under its former name `outlook-mcp`: that cache is still used as a fallback when the current one is absent, so deleting only the first file leaves a working refresh token on disk. To revoke fully, also remove the app at https://account.microsoft.com or in your organization's identity portal.
+
+## Troubleshooting
+
+- **`NotAuthenticatedError: Not authenticated`** — run `msgraph-mcp-login`. If it recurs immediately, a requested scope has not been consented yet; see the note under Entra setup.
+- **`ConfigError: Missing required env var`** — set it in your shell, in a `.env` in the working directory, or in your MCP host's env config.
+- **`Graph API 403: ErrorAccessDenied`** — the Entra app is missing a delegated permission, or it needs admin consent. Check the list above, then re-consent and sign in again.
+- **`Graph API 400: BadRequest — Syntax error`** from `search_messages` — the query goes to Graph's `$search` as KQL. Quote literal phrases (`"weekly report"`) or use fielded forms (`from:alice`). For predicates KQL cannot express, use `list_messages` with `filter=`.
+- **The host starts the server but lists no tools** — confirm it launches `msgraph-mcp` (or `uvx`) over stdio and can find that binary on its `PATH`.
+
+## Development
+
+See [CONTRIBUTING.md](https://github.com/timfurlong/msgraph-mcp/blob/main/CONTRIBUTING.md).

{msgraph_mcp_server-0.3.0 → msgraph_mcp_server-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "msgraph-mcp-server"
-version = "0.3.0"
+version = "0.3.2"
 description = "MCP server for Microsoft Graph: Outlook mail and calendar, plus read-only Microsoft Teams"
 readme = "README.md"
 license = "MIT"
@@ -33,6 +33,8 @@ Issues = "https://github.com/timfurlong/msgraph-mcp/issues"
 
 [project.scripts]
 msgraph-mcp = "msgraph_mcp.server:main"
+# Alias matching the PyPI distribution name, so `uvx msgraph-mcp-server` works.
+msgraph-mcp-server = "msgraph_mcp.server:main"
 msgraph-mcp-login = "msgraph_mcp.auth.cli:main"
 
 [build-system]
@@ -50,6 +52,11 @@ dev = [
     "ruff>=0.6",
 ]
 
+[tool.ruff]
+# Pinned rather than left implicit so a ruff release changing the default
+# cannot reformat the tree out from under CI.
+line-length = 88
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]

msgraph_mcp_server-0.3.2/server.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.timfurlong/msgraph-mcp",
+  "title": "MSGraph MCP",
+  "description": "MCP server for Microsoft Graph: Outlook mail and calendar, plus read-only Microsoft Teams",
+  "repository": {
+    "url": "https://github.com/timfurlong/msgraph-mcp",
+    "source": "github"
+  },
+  "version": "0.3.2",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "msgraph-mcp-server",
+      "version": "0.3.2",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "MSGRAPH_MCP_CLIENT_ID",
+          "description": "Client ID of your Entra (Azure AD) app registration",
+          "isRequired": true,
+          "isSecret": false
+        },
+        {
+          "name": "MSGRAPH_MCP_TENANT_ID",
+          "description": "Entra tenant ID (or 'common' / 'organizations' / 'consumers')",
+          "isRequired": true,
+          "isSecret": false
+        },
+        {
+          "name": "MSGRAPH_MCP_TOKEN_CACHE_PATH",
+          "description": "Override the token cache location (default ~/.msgraph-mcp/token_cache.bin)",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

{msgraph_mcp_server-0.3.0 → msgraph_mcp_server-0.3.2}/src/msgraph_mcp/auth/cli.py

@@ -33,8 +33,7 @@ def run_login() -> int:
     persist_cache(cache)
 
     username = (
-        result.get("id_token_claims", {}).get("preferred_username")
-        or "<unknown>"
+        result.get("id_token_claims", {}).get("preferred_username") or "<unknown>"
     )
     print(f"Logged in as {username}", flush=True)
     print(f"Token cache saved to {config.token_cache_path()}", flush=True)

{msgraph_mcp_server-0.3.0 → msgraph_mcp_server-0.3.2}/src/msgraph_mcp/auth/token.py

@@ -14,9 +14,7 @@ class NotAuthenticatedError(RuntimeError):
     """Raised when no valid token is available and silent refresh failed."""
 
 
-_LOGIN_HINT = (
-    "Not authenticated. Run `msgraph-mcp-login` in a terminal to sign in."
-)
+_LOGIN_HINT = "Not authenticated. Run `msgraph-mcp-login` in a terminal to sign in."
 
 
 def get_access_token() -> str: