zoo/owa-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Activity

w

Browse Source
This commit is contained in:
albnnc
2026-07-06 01:46:14 +03:00
parent 8b3e116062
commit a9497625b1
18 changed files with 5771 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+287
View File
@@ -0,0 +1,287 @@
# OWA MCP Server
MCP (Model Context Protocol) server for any Microsoft Exchange / OWA (Outlook Web Access) deployment. Gives LLM agents access to email, calendar, directory search, folders, availability, and meeting analytics via 30 tools.
Works with any on-premise or hosted Exchange server that exposes OWA.
## Quick Start
```bash
# Install
pip install -e .
# Add to your MCP client config with --owa-url
# Then use the login tool to paste your session cookies
```
## Install
Add to your MCP client config. Replace `https://owa.example.com` with your OWA URL.
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"exchange": {
"command": "uvx",
"args": [
"exchange-mcp-server",
"--owa-url", "https://owa.example.com"
]
}
}
}
```
**Cursor** (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"exchange": {
"command": "uvx",
"args": [
"exchange-mcp-server",
"--owa-url", "https://owa.example.com"
]
}
}
}
```
**Claude Code** (`.mcp.json`):
```json
{
"mcpServers": {
"exchange": {
"command": "uvx",
"args": [
"exchange-mcp-server",
"--owa-url", "https://owa.example.com"
]
}
}
}
```
## CLI Arguments
| Argument | Default | Required | Description |
|---|---|---|---|
| `--owa-url` | — | Yes | Base URL of the OWA instance (e.g. `https://owa.example.com`) |
| `--cookie-file` | `session-cookies.txt` | No | Path to session cookies file |
| `--transport` | `stdio` | — | `stdio`, `sse`, or `streamable-http` |
| `--token-hash` | — | For HTTP | SHA-256 hash of the bearer token |
| `--port` | `8000` | — | HTTP/SSE listener port |
| `--host` | `127.0.0.1` | — | HTTP/SSE listener host |
| `--enabled-tools` | — | No | Comma-separated whitelist of tool names |
| `--disabled-tools` | — | No | Comma-separated blacklist of tool names |
### Tool filtering examples
```bash
# Hide only the most dangerous tools
exchange-mcp-server --owa-url https://owa.example.com \
--disabled-tools "send_email,delete_email,cancel_meeting"
# Allow only email and calendar tools
exchange-mcp-server --owa-url https://owa.example.com \
--enabled-tools "get_emails,get_email,send_email,get_calendar_events,create_meeting"
# Whitelist a set, then remove one from it
exchange-mcp-server --owa-url https://owa.example.com \
--enabled-tools "get_emails,get_email,send_email,delete_email" \
--disabled-tools "delete_email"
# → only get_emails, get_email, send_email remain
```
## HTTP Transport
Run the server over HTTP (streamable-http or SSE) instead of stdio. This is
useful when the MCP client cannot spawn a local process, or when you want to
expose the server on a network.
### Installation
```bash
pip install -e ".[http]" # adds uvicorn + sse-starlette
```
### Start the server
```bash
# Compute the token hash once (store only the hash, never the plaintext token)
TOKEN_HASH=$(echo -n 'my-secret-token' | sha256sum | cut -d' ' -f1)
# stdio (default, for local MCP clients)
exchange-mcp-server --owa-url https://owa.example.com
# streamable-http (recommended for HTTP)
exchange-mcp-server \
--owa-url https://owa.example.com \
--transport streamable-http \
--token-hash "$TOKEN_HASH" \
--port 8000 \
--host 127.0.0.1
# SSE
exchange-mcp-server \
--owa-url https://owa.example.com \
--transport sse \
--token-hash "$TOKEN_HASH" \
--port 8000
```
### CLI arguments
| Argument | Default | Required | Description |
|---|---|---|---|
| `--owa-url` | — | Yes | Base URL of the OWA instance (e.g. `https://owa.example.com`) |
| `--cookie-file` | `session-cookies.txt` | No | Path to session cookies file |
| `--transport` | `stdio` | — | `stdio`, `sse`, or `streamable-http` |
| `--token-hash` | — | For HTTP | SHA-256 hash of the bearer token |
| `--port` | `8000` | — | HTTP/SSE listener port |
| `--host` | `127.0.0.1` | — | HTTP/SSE listener host |
| `--enabled-tools` | — | No | Comma-separated whitelist of tool names |
| `--disabled-tools` | — | No | Comma-separated blacklist of tool names |
### Client configuration (HTTP)
```json
{
"mcpServers": {
"exchange": {
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer my-secret-token"
}
}
}
}
```
### Authentication
The server stores only the SHA-256 hash of your token — the plaintext token
never touches the filesystem. Every HTTP request must include:
```
Authorization: Bearer <plaintext-token>
```
The server hashes the incoming token and compares it with the stored hash.
Pass the hash via `--token-hash`:
```bash
echo -n 'my-secret-token' | sha256sum
# → 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
```
### Security notes
- Always use a strong random token.
- Bind to `127.0.0.1` unless you have a reverse proxy / firewall.
- For `streamable-http` the client must send `Accept: text/event-stream`.
- The `--token-hash` is required whenever `--transport` is not `stdio`.
## Login
The `login` MCP tool accepts session cookies that you copy from your browser.
1. Log into OWA in your browser.
2. Open DevTools (F12) → Application → Cookies → select your OWA domain.
3. Copy all cookies as `name=value` pairs (one per line).
4. Call the `login` tool with the cookies string.
Example cookies string:
```
X-OWA-CANARY=abc123
CookieAuth1=def456
...
```
```
login(cookies="X-OWA-CANARY=abc123\nCookieAuth1=def456\n...")
```
On success, cookies are saved to `session-cookies.txt` and all tools become usable. When the session expires, repeat the steps.
## Tools (30)
### Email (10)
| Tool | Description |
|---|---|
| `get_emails` | List emails from a folder with filtering |
| `get_email` | Get full email content by ID |
| `send_email` | Send a new email |
| `reply_email` | Reply to an email |
| `forward_email` | Forward an email |
| `delete_email` | Delete an email |
| `move_email` | Move email to another folder |
| `mark_email_read` | Mark email as read/unread |
| `download_attachments` | Download file attachments from an email |
| `get_email_links` | Extract hyperlinks from an email body |
### Calendar (7)
| Tool | Description |
|---|---|
| `get_calendar_events` | Get events in a date range (supports recurring expansion) |
| `create_meeting` | Create a meeting with attendees |
| `update_meeting` | Update an existing meeting |
| `cancel_meeting` | Cancel a meeting and notify attendees |
| `respond_to_meeting` | Accept, decline, or tentatively accept |
| `download_event_attachments` | Download file attachments from a calendar event |
| `get_event_links` | Extract hyperlinks from the event description |
### Directory (1)
| Tool | Description |
|---|---|
| `find_person` | Search people in Active Directory |
### Folders (7)
| Tool | Description |
|---|---|
| `get_folders` | List mail folders with unread counts |
| `create_folder` | Create a new mail folder |
| `rename_folder` | Rename an existing folder |
| `empty_folder` | Empty all items from a folder |
| `delete_folder` | Delete a mail folder |
| `move_folder` | Move a folder to a different parent |
| `check_session` | Check if the OWA session is authenticated |
### Availability (2)
| Tool | Description |
|---|---|
| `find_free_time` | Find free slots in your calendar |
| `find_meeting_time` | Find common free slots for multiple people |
### Analytics (2)
| Tool | Description |
|---|---|
| `get_meeting_stats` | Meeting count statistics for multiple people |
| `get_meeting_contacts` | Connection matrix — who you meet with most |
### Auth (1)
| Tool | Description |
|---|---|
| `login` | Authenticate to OWA using browser session cookies |
## Files
```
exchange_mcp/
server.py # FastMCP server entry point
owa_client.py # OWA HTTP client
tools/
email.py # Email tools
calendar.py # Calendar tools
people.py # Directory search
folders.py # Folder management & session check
availability.py # Free time / meeting time
analytics.py # Meeting stats & contacts
auth.py # Login tool
pyproject.toml # Package config
```