outlook-mcp-com 0.1.0__tar.gz

outlook_mcp_com-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Kopelman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

outlook_mcp_com-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: outlook-mcp-com
+Version: 0.1.0
+Summary: MCP server controlling Microsoft Outlook desktop via the Win32 COM API
+Author: Adam Kopelman
+License: MIT License
+        
+        Copyright (c) 2026 Adam Kopelman
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/adamkopelman/outlook-mcp
+Project-URL: Repository, https://github.com/adamkopelman/outlook-mcp
+Keywords: mcp,outlook,windows,com,pywin32,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2
+Requires-Dist: pywin32>=306; sys_platform == "win32"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# outlook-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets Claude (or any MCP
+client) control **Microsoft Outlook desktop on Windows** through the Win32 COM
+API — read and send email, manage your calendar, save attachments, and work
+with tasks and notes, all against the Outlook profile you are already signed
+in to. No Azure app registration, no Graph API tokens.
+
+## Requirements
+
+- **Windows** with **classic Outlook desktop** installed and a configured
+  mail profile.
+  > ⚠️ The "new Outlook" (`olk.exe`) does **not** expose a COM API and will
+  > not work. You need classic Outlook (Microsoft 365 / Office 2016+).
+- **Python 3.10+**
+- The server only *runs* on Windows; the test suite runs anywhere (COM access
+  is mocked).
+
+## Installation
+
+```bash
+git clone https://github.com/adamkopelman/outlook-mcp.git
+cd outlook-mcp
+pip install .
+```
+
+This installs the `outlook-mcp` console command (and `pywin32` on Windows).
+
+## Hooking it up to Claude
+
+**As a Claude Code plugin** (recommended for Claude Code) — this repo is itself a
+plugin (`.claude-plugin/plugin.json`) that registers the `outlook` MCP server
+for you. After `pip install .` (above), either:
+
+```bash
+# Try it locally without installing anything into Claude Code's config:
+claude --plugin-dir /path/to/outlook-mcp
+
+# Or install it properly, from a local checkout or directly from GitHub:
+claude plugin install outlook-mcp@/path/to/outlook-mcp
+claude plugin install outlook-mcp@github.com/adamkopelman/outlook-mcp
+```
+
+The plugin launches the server as `python -m outlook_mcp` rather than via the
+`outlook-mcp` console script, so it works even if pip's script directory isn't
+on `PATH` — it just needs `outlook_mcp` importable by whichever `python` is
+first on `PATH`.
+
+**Claude Desktop** — add to `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "outlook-mcp"
+    }
+  }
+}
+```
+
+If `outlook-mcp` isn't on PATH, use the full interpreter instead:
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "C:\\Path\\To\\python.exe",
+      "args": ["-m", "outlook_mcp"]
+    }
+  }
+}
+```
+
+**Claude Code (manual, without the plugin):**
+
+```bash
+claude mcp add outlook -- outlook-mcp
+```
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `list_folders` | List mail folders with item/unread counts |
+| `list_emails` | Recent emails in a folder (newest first, `unread_only` option) |
+| `search_emails` | Search subject/sender/body, optional `since_days` window |
+| `get_email` | Full email by id (body, recipients, attachment names) |
+| `send_email` | **Send immediately** (to/cc/bcc, plain or HTML body) |
+| `create_draft` | Compose and save to Drafts without sending |
+| `reply_email` | Reply / reply-all (send, or save as draft with `send=false`) |
+| `move_email` | Move an email to another folder (returns its new id) |
+| `delete_email` | Move an email to Deleted Items |
+| `list_events` | Calendar events in a date range (recurrences expanded) |
+| `get_event` | Full event details including attendees |
+| `create_event` | Create an appointment — adding `attendees` sends invites |
+| `respond_to_meeting` | Accept / decline / tentative a meeting invite |
+| `list_attachments` | List an email's attachments |
+| `save_attachments` | Save attachments to a local directory |
+| `list_tasks` | List tasks (open only by default) |
+| `create_task` | Create a task with due date and importance |
+| `complete_task` | Mark a task complete |
+| `list_notes` | List sticky notes |
+| `get_note` | Read a note's full body |
+| `create_note` | Create a sticky note |
+
+Items are addressed by an opaque `id` returned from list/search tools.
+**Ids change when an item moves folders** — `move_email` returns the new id,
+and a stale id produces a clear "item not found" error.
+
+## Security notes
+
+- `send_email`, `reply_email`, `create_event` (with attendees) and
+  `respond_to_meeting` act **immediately as the signed-in Outlook user**,
+  with no confirmation step inside the server. If you want a human in the
+  loop, prefer `create_draft` / `send=false`, or deny the sending tools in
+  your MCP client's permission settings.
+- Outlook's object model guard may show a *"A program is trying to send an
+  e-mail message on your behalf"* prompt, typically when no up-to-date
+  antivirus is registered with Windows or group policy demands it. The
+  prompt blocks the tool call until answered. Do **not** disable Outlook
+  security to avoid it.
+- `save_attachments` writes to any local path the MCP client asks for.
+
+## Troubleshooting
+
+- *"Outlook is not available..."* — you're not on Windows, or classic
+  Outlook isn't installed.
+- The first tool call may take a few seconds while Outlook launches.
+- *"Item not found"* — the id went stale (item moved or was deleted);
+  list/search again to get a fresh id.
+- Date filters use Outlook's JET format internally; if `search_emails` with
+  `since_days` misbehaves on a heavily localized system, try without it and
+  filter by eye.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+The COM layer lives in `outlook_mcp/outlook/client.py` behind the
+`OutlookClientBase` interface (`outlook_mcp/outlook/base.py`); tests run on
+any OS against an in-memory fake (`tests/conftest.py`).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

outlook_mcp_com-0.1.0/README.md

@@ -0,0 +1,148 @@
+# outlook-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that lets Claude (or any MCP
+client) control **Microsoft Outlook desktop on Windows** through the Win32 COM
+API — read and send email, manage your calendar, save attachments, and work
+with tasks and notes, all against the Outlook profile you are already signed
+in to. No Azure app registration, no Graph API tokens.
+
+## Requirements
+
+- **Windows** with **classic Outlook desktop** installed and a configured
+  mail profile.
+  > ⚠️ The "new Outlook" (`olk.exe`) does **not** expose a COM API and will
+  > not work. You need classic Outlook (Microsoft 365 / Office 2016+).
+- **Python 3.10+**
+- The server only *runs* on Windows; the test suite runs anywhere (COM access
+  is mocked).
+
+## Installation
+
+```bash
+git clone https://github.com/adamkopelman/outlook-mcp.git
+cd outlook-mcp
+pip install .
+```
+
+This installs the `outlook-mcp` console command (and `pywin32` on Windows).
+
+## Hooking it up to Claude
+
+**As a Claude Code plugin** (recommended for Claude Code) — this repo is itself a
+plugin (`.claude-plugin/plugin.json`) that registers the `outlook` MCP server
+for you. After `pip install .` (above), either:
+
+```bash
+# Try it locally without installing anything into Claude Code's config:
+claude --plugin-dir /path/to/outlook-mcp
+
+# Or install it properly, from a local checkout or directly from GitHub:
+claude plugin install outlook-mcp@/path/to/outlook-mcp
+claude plugin install outlook-mcp@github.com/adamkopelman/outlook-mcp
+```
+
+The plugin launches the server as `python -m outlook_mcp` rather than via the
+`outlook-mcp` console script, so it works even if pip's script directory isn't
+on `PATH` — it just needs `outlook_mcp` importable by whichever `python` is
+first on `PATH`.
+
+**Claude Desktop** — add to `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "outlook-mcp"
+    }
+  }
+}
+```
+
+If `outlook-mcp` isn't on PATH, use the full interpreter instead:
+
+```json
+{
+  "mcpServers": {
+    "outlook": {
+      "command": "C:\\Path\\To\\python.exe",
+      "args": ["-m", "outlook_mcp"]
+    }
+  }
+}
+```
+
+**Claude Code (manual, without the plugin):**
+
+```bash
+claude mcp add outlook -- outlook-mcp
+```
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `list_folders` | List mail folders with item/unread counts |
+| `list_emails` | Recent emails in a folder (newest first, `unread_only` option) |
+| `search_emails` | Search subject/sender/body, optional `since_days` window |
+| `get_email` | Full email by id (body, recipients, attachment names) |
+| `send_email` | **Send immediately** (to/cc/bcc, plain or HTML body) |
+| `create_draft` | Compose and save to Drafts without sending |
+| `reply_email` | Reply / reply-all (send, or save as draft with `send=false`) |
+| `move_email` | Move an email to another folder (returns its new id) |
+| `delete_email` | Move an email to Deleted Items |
+| `list_events` | Calendar events in a date range (recurrences expanded) |
+| `get_event` | Full event details including attendees |
+| `create_event` | Create an appointment — adding `attendees` sends invites |
+| `respond_to_meeting` | Accept / decline / tentative a meeting invite |
+| `list_attachments` | List an email's attachments |
+| `save_attachments` | Save attachments to a local directory |
+| `list_tasks` | List tasks (open only by default) |
+| `create_task` | Create a task with due date and importance |
+| `complete_task` | Mark a task complete |
+| `list_notes` | List sticky notes |
+| `get_note` | Read a note's full body |
+| `create_note` | Create a sticky note |
+
+Items are addressed by an opaque `id` returned from list/search tools.
+**Ids change when an item moves folders** — `move_email` returns the new id,
+and a stale id produces a clear "item not found" error.
+
+## Security notes
+
+- `send_email`, `reply_email`, `create_event` (with attendees) and
+  `respond_to_meeting` act **immediately as the signed-in Outlook user**,
+  with no confirmation step inside the server. If you want a human in the
+  loop, prefer `create_draft` / `send=false`, or deny the sending tools in
+  your MCP client's permission settings.
+- Outlook's object model guard may show a *"A program is trying to send an
+  e-mail message on your behalf"* prompt, typically when no up-to-date
+  antivirus is registered with Windows or group policy demands it. The
+  prompt blocks the tool call until answered. Do **not** disable Outlook
+  security to avoid it.
+- `save_attachments` writes to any local path the MCP client asks for.
+
+## Troubleshooting
+
+- *"Outlook is not available..."* — you're not on Windows, or classic
+  Outlook isn't installed.
+- The first tool call may take a few seconds while Outlook launches.
+- *"Item not found"* — the id went stale (item moved or was deleted);
+  list/search again to get a fresh id.
+- Date filters use Outlook's JET format internally; if `search_emails` with
+  `since_days` misbehaves on a heavily localized system, try without it and
+  filter by eye.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+The COM layer lives in `outlook_mcp/outlook/client.py` behind the
+`OutlookClientBase` interface (`outlook_mcp/outlook/base.py`); tests run on
+any OS against an in-memory fake (`tests/conftest.py`).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

outlook_mcp_com-0.1.0/outlook_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""MCP server controlling Microsoft Outlook desktop via the Win32 COM API."""
+
+__version__ = "0.1.0"

outlook_mcp_com-0.1.0/outlook_mcp/__main__.py

@@ -0,0 +1,4 @@
+from outlook_mcp.server import main
+
+if __name__ == "__main__":
+    main()

outlook_mcp_com-0.1.0/outlook_mcp/constants.py

@@ -0,0 +1,75 @@
+"""Outlook object model constants, hardcoded so we never depend on
+win32com.client.constants (which requires makepy/gencache type libraries).
+
+Values come from the documented Outlook enumerations:
+https://learn.microsoft.com/en-us/office/vba/api/outlook.oldefaultfolders
+"""
+
+# OlDefaultFolders
+OL_FOLDER_DELETED_ITEMS = 3
+OL_FOLDER_OUTBOX = 4
+OL_FOLDER_SENT_MAIL = 5
+OL_FOLDER_INBOX = 6
+OL_FOLDER_CALENDAR = 9
+OL_FOLDER_CONTACTS = 10
+OL_FOLDER_JOURNAL = 11
+OL_FOLDER_NOTES = 12
+OL_FOLDER_TASKS = 13
+OL_FOLDER_DRAFTS = 16
+
+# OlItemType (Application.CreateItem)
+OL_MAIL_ITEM = 0
+OL_APPOINTMENT_ITEM = 1
+OL_CONTACT_ITEM = 2
+OL_TASK_ITEM = 3
+OL_JOURNAL_ITEM = 4
+OL_NOTE_ITEM = 5
+OL_POST_ITEM = 6
+
+# OlBodyFormat
+OL_FORMAT_PLAIN = 1
+OL_FORMAT_HTML = 2
+OL_FORMAT_RICHTEXT = 3
+
+# OlMeetingResponse (AppointmentItem.Respond)
+OL_MEETING_TENTATIVE = 2
+OL_MEETING_ACCEPTED = 3
+OL_MEETING_DECLINED = 4
+
+# OlMeetingStatus
+OL_NONMEETING = 0
+OL_MEETING = 1
+
+# OlTaskStatus
+OL_TASK_NOT_STARTED = 0
+OL_TASK_IN_PROGRESS = 1
+OL_TASK_COMPLETE = 2
+
+# OlImportance
+OL_IMPORTANCE_LOW = 0
+OL_IMPORTANCE_NORMAL = 1
+OL_IMPORTANCE_HIGH = 2
+
+# Friendly folder names accepted by tools, mapped to default folder ids.
+FOLDER_NAME_TO_ID = {
+    "inbox": OL_FOLDER_INBOX,
+    "sent": OL_FOLDER_SENT_MAIL,
+    "sent items": OL_FOLDER_SENT_MAIL,
+    "drafts": OL_FOLDER_DRAFTS,
+    "deleted": OL_FOLDER_DELETED_ITEMS,
+    "deleted items": OL_FOLDER_DELETED_ITEMS,
+    "trash": OL_FOLDER_DELETED_ITEMS,
+    "outbox": OL_FOLDER_OUTBOX,
+}
+
+IMPORTANCE_NAME_TO_ID = {
+    "low": OL_IMPORTANCE_LOW,
+    "normal": OL_IMPORTANCE_NORMAL,
+    "high": OL_IMPORTANCE_HIGH,
+}
+
+MEETING_RESPONSE_TO_ID = {
+    "accept": OL_MEETING_ACCEPTED,
+    "decline": OL_MEETING_DECLINED,
+    "tentative": OL_MEETING_TENTATIVE,
+}

outlook_mcp_com-0.1.0/outlook_mcp/errors.py

@@ -0,0 +1,26 @@
+"""Error types and COM error formatting."""
+
+
+class ToolError(Exception):
+    """User-facing tool failure (bad input, missing item, COM error)."""
+
+
+def format_com_error(exc: BaseException) -> str:
+    """Turn a pywintypes.com_error into a readable one-line message.
+
+    com_error args are (hresult, strerror, excepinfo, argerror) where
+    excepinfo is None or a 6-tuple whose third element is the source
+    application's own description (usually the most useful text).
+    """
+    try:
+        hresult = exc.args[0]
+        strerror = exc.args[1]
+        excepinfo = exc.args[2]
+    except (IndexError, AttributeError):
+        return f"Outlook COM error: {exc}"
+    detail = None
+    if excepinfo and len(excepinfo) > 2 and excepinfo[2]:
+        detail = str(excepinfo[2]).strip()
+    if detail:
+        return f"Outlook error: {detail} (HRESULT {hresult})"
+    return f"Outlook error: {strerror} (HRESULT {hresult})"

outlook_mcp_com-0.1.0/outlook_mcp/outlook/base.py

@@ -0,0 +1,118 @@
+"""Abstract Outlook client interface.
+
+This module is importable on any platform. The real implementation
+(WindowsOutlookClient in outlook_mcp.outlook.client) is only imported on
+Windows; tests inject a fake implementing this interface.
+
+All methods accept and return plain JSON-able Python values (str, int,
+bool, dict, list). Items are addressed by an opaque ``id`` string of the
+form ``"{EntryID}|{StoreID}"`` returned from list/search calls.
+"""
+
+from typing import Optional
+
+from outlook_mcp.errors import ToolError
+
+
+class OutlookClientBase:
+    # ---- Email -----------------------------------------------------
+    def list_folders(self) -> list:
+        raise NotImplementedError
+
+    def list_emails(self, folder: str = "inbox", count: int = 10,
+                    unread_only: bool = False) -> list:
+        raise NotImplementedError
+
+    def search_emails(self, query: str, folder: str = "inbox", count: int = 10,
+                      since_days: Optional[int] = None) -> list:
+        raise NotImplementedError
+
+    def get_email(self, email_id: str, prefer_html: bool = False) -> dict:
+        raise NotImplementedError
+
+    def send_email(self, to: list, subject: str, body: str,
+                   cc: Optional[list] = None, bcc: Optional[list] = None,
+                   html: bool = False) -> dict:
+        raise NotImplementedError
+
+    def create_draft(self, to: list, subject: str, body: str,
+                     cc: Optional[list] = None, bcc: Optional[list] = None,
+                     html: bool = False) -> dict:
+        raise NotImplementedError
+
+    def reply_email(self, email_id: str, body: str, reply_all: bool = False,
+                    html: bool = False, send: bool = True) -> dict:
+        raise NotImplementedError
+
+    def move_email(self, email_id: str, target_folder: str) -> dict:
+        raise NotImplementedError
+
+    def delete_email(self, email_id: str) -> dict:
+        raise NotImplementedError
+
+    # ---- Calendar --------------------------------------------------
+    def list_events(self, start_date: Optional[str] = None,
+                    end_date: Optional[str] = None) -> list:
+        raise NotImplementedError
+
+    def get_event(self, event_id: str) -> dict:
+        raise NotImplementedError
+
+    def create_event(self, subject: str, start: str, end: str,
+                     body: Optional[str] = None, location: Optional[str] = None,
+                     attendees: Optional[list] = None, all_day: bool = False,
+                     reminder_minutes: Optional[int] = None) -> dict:
+        raise NotImplementedError
+
+    def respond_to_meeting(self, event_id: str, response: str,
+                           comment: Optional[str] = None,
+                           send: bool = True) -> dict:
+        raise NotImplementedError
+
+    # ---- Attachments -----------------------------------------------
+    def list_attachments(self, email_id: str) -> list:
+        raise NotImplementedError
+
+    def save_attachments(self, email_id: str, save_dir: str,
+                         attachment_names: Optional[list] = None) -> list:
+        raise NotImplementedError
+
+    # ---- Tasks -----------------------------------------------------
+    def list_tasks(self, include_completed: bool = False) -> list:
+        raise NotImplementedError
+
+    def create_task(self, subject: str, body: Optional[str] = None,
+                    due_date: Optional[str] = None,
+                    importance: str = "normal") -> dict:
+        raise NotImplementedError
+
+    def complete_task(self, task_id: str) -> dict:
+        raise NotImplementedError
+
+    # ---- Notes -----------------------------------------------------
+    def list_notes(self) -> list:
+        raise NotImplementedError
+
+    def get_note(self, note_id: str) -> dict:
+        raise NotImplementedError
+
+    def create_note(self, body: str) -> dict:
+        raise NotImplementedError
+
+
+class UnavailableClient(OutlookClientBase):
+    """Stands in when not running on Windows: the server starts and lists
+    tools anywhere, but every call explains the platform requirement."""
+
+    _MESSAGE = ("Outlook is not available: this server requires Windows with "
+                "classic Outlook desktop installed (Outlook COM automation).")
+
+    def __getattribute__(self, name):
+        base = object.__getattribute__(self, "__class__").__mro__[1]
+        if name.startswith("_") or not callable(getattr(base, name, None)):
+            return object.__getattribute__(self, name)
+
+        def _unavailable(*args, **kwargs):
+            raise ToolError(UnavailableClient._MESSAGE)
+
+        return _unavailable