jayozer/agentbuilder-outlook-mcp

Agentbuilder Outlook MCP Server

FastMCP server for sending Outlook mail via Microsoft Graph. This project exists because the Agent Builder Outlook connector does not provide a send-email capability; the MCP server delivers that missing tool by exposing a single send_outlook_mail entry point that validates payloads, obtains access tokens, and calls the Graph sendMail endpoint.

Prerequisites

• Python 3.10+
• Microsoft Outlook/Graph account with Mail.Send permission (delegated token or app registration)
• uv (recommended) or pip

Installation

uv pip install .

Environment Variables

Set the following in .env (create from .env.example):

• GRAPH_USER_ACCESS_TOKEN – Optional delegated bearer token (e.g., from Graph Explorer) for quick testing.
• GRAPH_DEFAULT_SENDER – Mailbox to send from, e.g., user@outlook.com.
• GRAPH_TENANT_ID, GRAPH_CLIENT_ID, GRAPH_CLIENT_SECRET – Required only for app-only client credentials flow.

Load them before running:

set -a; source .env; set +a

Local Usage

Dry run (no email sent):

python3 - <<'PY'
from server import send_outlook_mail_impl

result = send_outlook_mail_impl(
    subject="Dry Run",
    body="Payload preview only.",
    to=["recipient@example.com"],
    dry_run=True,
)
print(result)
PY

Send a live message (dry_run=False) once configuration is confirmed. To expose the MCP tool to clients:

fastmcp run server.py

Remote Deployment

The server is deployed on FastMCP at https://agentbuilder-outlook-mcp.fastmcp.app/mcp. Connect your MCP-compatible client (Claude Desktop, Cursor, etc.) using this URL.

For local validation before hitting the remote server:

fastmcp run server.py

Multi-Tenant Configuration

This server supports multi-tenant usage where each user provides their own Microsoft credentials when calling the send_outlook_mail tool. The server itself stores NO credentials - all authentication happens per-request.

Two Authentication Methods

The MCP server supports both personal Microsoft accounts and organizational accounts through two different authentication flows:

Method 1: Personal Microsoft Accounts (@outlook.com, @hotmail.com, @live.com)

Best for: Individual users, testing, personal email automation

Authentication: Delegated permissions with user sign-in

Setup Steps:

1. Go to Microsoft Graph Explorer
2. Sign in with your personal Microsoft account
3. Run any query (e.g., GET /me)
4. Grant Mail.Send permission when prompted
5. Click the "Access token" tab and copy the token
6. Use the token in your MCP client:

send_outlook_mail(
    subject="Test Email",
    body="Hello from my personal account!",
    to=["recipient@example.com"],
    access_token="EwBIBMl6BAAU...",  # Your Graph Explorer token
    sender="your.personal@outlook.com"
)

Token Format: Non-JWT proprietary format (starts with EwB..., no dots) Expiration: ~1 hour (must refresh manually) Permissions: Delegated (acts as the signed-in user)

Note: Personal account tokens use Microsoft's proprietary encrypted format. This is normal and works correctly with the Graph API, despite not being standard JWTs.

Method 2: Organizational Accounts (Microsoft 365 / Azure AD)

Best for: Production applications, service accounts, automated workflows

Authentication: Client credentials (application-only, no user sign-in)

Prerequisites:

• Azure AD tenant with Microsoft 365
• Exchange Online mailbox provisioned
• Azure AD app registration

Setup Steps: See for detailed instructions

Quick Summary:

1. Create Azure AD app registration
2. Add Mail.Send application permission
3. Grant admin consent
4. Create client secret
5. Use credentials in your MCP client:

send_outlook_mail(
    subject="Automated Email",
    body="Sent via client credentials",
    to=["recipient@example.com"],
    tenant_id="your-tenant-id",
    client_id="your-client-id",
    client_secret="your-client-secret",
    sender="user@company.com"  # Must be valid organizational mailbox
)

Token Format: Standard JWT (starts with eyJ..., has 3 parts separated by dots) Expiration: Automatically refreshed by the server Permissions: Application (app acts independently, not as a user)

Comparison Table

Single-Tenant Fallback (Optional)

For backwards compatibility, if no credential parameters are provided, the server falls back to environment variables:

• GRAPH_TENANT_ID
• GRAPH_CLIENT_ID
• GRAPH_CLIENT_SECRET
• GRAPH_DEFAULT_SENDER
• GRAPH_USER_ACCESS_TOKEN

This allows running a single-tenant server where all users share the same Outlook account. Not recommended for multi-tenant deployments.

Testing

uv pip install .[dev]
pytest

Unit tests cover token acquisition and payload construction.

Deployment Notes

• fastmcp.json is configured for fastmcp run and FastMCP Cloud.
• Secrets should be supplied via environment variables on the target platform.
• See todo.md for remaining tasks and deployment checklist.