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.Sendpermission (delegated token or app registration) uv(recommended) orpip
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:
- Go to Microsoft Graph Explorer
- Sign in with your personal Microsoft account
- Run any query (e.g., GET /me)
- Grant
Mail.Sendpermission when prompted - Click the "Access token" tab and copy the token
- 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 AZURE_SETUP.md for detailed instructions
Quick Summary:
- Create Azure AD app registration
- Add
Mail.Sendapplication permission - Grant admin consent
- Create client secret
- 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
| Feature | Personal Accounts | Organizational Accounts |
|---|---|---|
| Account Type | @outlook.com, @hotmail.com, @live.com | @company.com (Microsoft 365) |
| Authentication | Delegated (user sign-in) | Application (client credentials) |
| Token Source | Graph Explorer | Azure AD app registration |
| Token Format | Proprietary (EwB...) | JWT (eyJ...) |
| Token Lifespan | 1 hour | Auto-renewed |
| Best For | Testing, personal use | Production, automation |
| Cost | Free | Requires M365 license (~$6/month) |
| Setup Complexity | Simple (2 minutes) | Moderate (15 minutes) |
Single-Tenant Fallback (Optional)
For backwards compatibility, if no credential parameters are provided, the server falls back to environment variables:
GRAPH_TENANT_IDGRAPH_CLIENT_IDGRAPH_CLIENT_SECRETGRAPH_DEFAULT_SENDERGRAPH_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.jsonis configured forfastmcp runand FastMCP Cloud.- Secrets should be supplied via environment variables on the target platform.
- See
todo.mdfor remaining tasks and deployment checklist.