MailNet MCP Server: Gmail and Outlook Orchestration

Overview

MailNet MCP Server is a lightweight orchestration server that exposes Gmail and Outlook functionality through the Model Context Protocol (MCP). It is intended for developers who want to connect language models or automation agents to real email accounts in a structured, secure way. By implementing an MCP-compatible surface, the server presents mailbox operations (search, read, send, attachment handling) as reusable tools that models or agents can call.

The server’s main benefit is to separate provider-specific complexities (OAuth, mailbox APIs, MIME handling) from agent logic. Instead of embedding Gmail- or Outlook-specific code inside every model integration, you register the MailNet tools with your MCP-aware runtime and let the server handle authentication, rate limiting, and payload normalization. This makes it easier to build multi-account, multi-provider agents and to reason about side effects.

Features

• Exposes Gmail and Outlook operations as MCP tools (send, read, search, list threads)
• OAuth credential management for Gmail (Google OAuth2) and Outlook (Microsoft OAuth2)
• Attachment download/upload and MIME parsing
• Unified message schema across providers for easier agent consumption
• Webhooks / push notifications for new mail (optional)
• ACLs and allowed-scope configuration to limit agent capabilities
• Docker-friendly and minimal configuration using environment variables

Core components

1. Auth Manager — handles OAuth flows, token refresh, and secure storage of credentials.
2. Provider Adapters — provider-specific logic (Gmail API, Microsoft Graph) that normalizes messages.
3. MCP Bridge — the protocol layer that exposes tools and executes model-initiated calls.
4. Parser & Attachment Service — MIME parsing, file streaming, and temporary storage.
5. Admin API & Webhooks — health checks, tool listing, and incoming-mail notifications.

Installation / Configuration

Clone the repository, then build/run with Docker (recommended) or run locally if you prefer.

Using Docker:

git clone https://github.com/Astroa7m/MailNet-MCP-Server.git
cd MailNet-MCP-Server

# Build image
docker build -t mailnet-mcp .

# Run (example)
docker run -d \
  -e MCP_PORT=8080 \
  -e GMAIL_CLIENT_ID=your-google-client-id \
  -e GMAIL_CLIENT_SECRET=your-google-client-secret \
  -e OUTLOOK_CLIENT_ID=your-ms-client-id \
  -e OUTLOOK_CLIENT_SECRET=your-ms-client-secret \
  -p 8080:8080 \
  --name mailnet mailnet-mcp

Local (node/python example placeholder — follow repo-specific docs):

# If project uses Node.js
npm install
npm run start

# If project uses Python
pip install -r requirements.txt
python -m mailnet_mcp.server

Environment variables (typical):

• MCP_PORT — port to listen on (default: 8080)
• GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET — Google OAuth2 credentials
• OUTLOOK_CLIENT_ID, OUTLOOK_CLIENT_SECRET — Microsoft OAuth2 credentials
• STORAGE_PATH — path for temporary attachments
• ALLOWED_SCOPES — comma-separated scopes or tool names agents may call

Store long-lived tokens securely (database or secret store). For production, front MailNet with TLS and restrict network access to only trusted model hosts.

Available Tools / Resources

The server publishes a set of MCP tools. Common tool names and operations:

Example MCP endpoints:

• GET /mcp/tools — list registered tools and schemas
• POST /mcp/execute — execute a tool call (JSON RPC-like payload)
• POST /webhook/mail — incoming-mail webhook (optional)
• GET /health — health/metrics

Example /mcp/execute payload:

{
  "tool": "gmail.send",
  "account_id": "user-123",
  "input": {
    "to": ["[email protected]"],
    "subject": "Monthly report",
    "body": "Attached is the report.",
    "attachments": [
      {"name": "report.pdf", "url": "https://..."}
    ]
  }
}

Use Cases

• LLM-based assistant sending emails: a conversational agent with model access to MailNet can draft and send messages after user confirmation. The model requests the “gmail.send” tool with the composed message; MailNet enforces ACLs and executes the send.
• Cross-account search & summarization: a summarization agent queries both Gmail and Outlook via “gmail.search” and “outlook.search”, retrieves relevant messages with “get”, and returns a distilled summary without the agent needing provider-specific code.
• Automated triage and response: an automation pipeline periodically calls MailNet search tools to find unread messages matching criteria, uses a code-execution or template engine to prepare replies, and posts them using the appropriate send tool.
• Attachment extraction for downstream processing: a data pipeline uses “attachments.get” to stream attachments out to a processing service (OCR, classification) without exposing raw credentials to that service.

Getting started tips

• Start with a test Gmail/Outlook account and minimal scopes (send, read) when experimenting.
• Register MailNet tools with your MCP runtime and verify tool schemas before granting model access.
• Log and monitor token refresh errors — OAuth errors are the most common operational issue.
• Keep attachment storage ephemeral and scan files if needed for security.

For detailed API shapes, authentication steps, and deployment examples, consult the repository README and code examples in the repo.