MailNet MCP Server

MailNet Server is a unified, agentic email orchestration server built for the Model Context Protocol. It supports Gmail and Outlook with standardized metadata, secure credential injection, and a rich toolset for assistant-driven workflows. It is the MCP server that powers MailNet Mailing Agentic AI, live at getmailnet.com.

---

Features

• Unified Gmail + Outlook abstraction
• Automatic token refresh and credential hygiene
• Standardized base class for provider extension
• Agentic email settings endpoint (tone, signature, thread context, etc.)
• Modular toolset: send, read, search, label, archive, reply, delete, draft

---

How it fits into MailNet

In the deployed MailNet stack this server runs as its own container (mcp, streamable HTTP on port 9111) and is the only component that talks to mailboxes. Everything email-shaped goes through it:

LangGraph agent (api)  ──┐
                         ├──>  MCP server :9111  ──>  provider layer  ──>  Gmail API
Scheduler (APScheduler) ─┘        (this repo)                        └──>  Microsoft Graph

• Per-request credentials, no stored state. The agent and the scheduler pass each user's OAuth tokens as encrypted HTTP headers on every call; the server decrypts, refreshes if needed, acts, and forgets. It holds no user database.
• One tool surface, two providers. Tools like send_email, read_emails, and search_emails accept an optional provider parameter; the provider layer hides the differences between the Gmail API and Microsoft Graph.
• Standalone by design. The same server also runs solo for local/Claude Desktop use with token files, as described below — MailNet is one consumer of it, not a requirement.

---

Installation

Running the full MailNet application (web UI, agent, and this server together)? Follow the MailNet repo's Getting started instead; it wires this server up via Docker Compose automatically. The steps below are for running the MCP server standalone (for example with Claude Desktop).

1. Manual Clone & Launch

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

Install requirements

pip install -r requirements.txt

Note if you are going to use uv for launching you should first install it via:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Launch

Either with uv via:

uv run -m mcp_launcher.server

or

python -m mcp_launcher.server

Acquiring Azure Token (Personal local use)

1. Go to email_client/outlook_helpers.py.
2. run the file (by default runs acquiring_azure_token_for_personal_use function. To acquire client_id & client_secret Please check Azure Authorization Guide And make sure to add them to your env vars with the names shown below.

def acquiring_azure_token_for_personal_use():
    load_dotenv()
    client_id = os.getenv("AZURE_APPLICATION_CLIENT_ID")
    client_secret = os.getenv("AZURE_SECRET_VALUE")
    OutlookClient(client_id=client_id, client_secret=client_secret,
                                 redirect_uri="http://localhost:3000/callback")

It will do the following:

• launch the browser and prompt you to sign in to your outlook account.
• After successful login and approval of permissions, it will redirect you to http://localhost:3000/callback unless you specified different url in the constructor via redirect_uri param.
• Copy the code after code= and before &client_info within the browser url and paste it in the terminal where you launched the file.
• Done now you will have your azure token under email_client named azure_token.json by default (can be changed via token_file_name param in OutlookClient constructor).

3. Provide that path to AZURE_PREFERRED_TOKEN_FILE_PATH env variable and you are good to go.

---

Acquiring Google Token (Personal local use)

1. Go to email_client/gmail_helpers.py.
2. run the file (by default runs acquiring_google_token_for_personal_use function. To acquire google_credentials_file Please check Google Authorization Guide And make sure to add the path to it in your env vars with the name shown below.

def acquiring_google_token_for_personal_use():
    load_dotenv()
    google_credentials_file = os.getenv("GOOGLE_CREDENTIALS_FILE_PATH")
    GmailClient(credential_file=google_credentials_file)

It will do the following:

• launch the browser and prompt you to sign in to your gmail account.
• After successful login and approval of permissions, it will redirect you to a window with a message The authentication flow has completed. You may close this window. that means you are done here.
• Done now you will have your google token under email_client named google_token.json by default (can be changed via token_file_name param in GmailClient constructor).

3. Provide that path to GOOGLE_CREDENTIALS_FILE_PATH env variable and you are good to go.

---

Environment Variables

Check the Azure Authorization Guide and Google Authorization Guide to learn how to set up both accounts and get your credentials ready.

Set your environment variables for provider credentials:

Gmail

GOOGLE_CREDENTIALS_FILE_PATH=path/to/google_credentials.json
GOOGLE_PREFERRED_TOKEN_FILE_PATH=path/to/google_token.json

Outlook (Azure)

AZURE_APPLICATION_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET_VALUE=your-secret
AZURE_PREFERRED_TOKEN_FILE_PATH=path/to/azure_token.json

Other (Important for local use)

The following env variable is important to be set when running it locally or for Claude Desktop. The value deosn't matter but as long as the field is there you will be able to run it locally. It was introduced to make the server flexible to be run over http/s or stdio and to route the server to either look for credentials in local files or expect it from the client via http/s headers.

is_local="true"

---

Claude Desktop Integration

Add the following to your claude_desktop_config.json:

{
  "mcpservers": {
    "email_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Path\\To\\mcp-server",
        "run",
        "-m",
        "mcp_launcher.server"
      ],
      "env": {
        "AZURE_APPLICATION_CLIENT_ID": "<AZURE_APPLICATION_CLIENT_ID>",
        "AZURE_CLIENT_SECRET_VALUE": "<AZURE_CLIENT_SECRET_VALUE>",
        "AZURE_PREFERRED_TOKEN_FILE_PATH": "C:\\Path\\To\\azure_token.json",
        "GOOGLE_CREDENTIALS_FILE_PATH": "C:\\Path\\To\\google_credentials.json",
        "GOOGLE_PREFERRED_TOKEN_FILE_PATH": "C:\\Path\\To\\google_token.json",
        "is_local": "true"
      }
    }
  }
}

---

Agentic Email Settings

You can view settings via the load_email_settings tool or update them via the update_email_settings tool.

{
  "language": "en",
  "tone": "formal",
  "writing_style": "clear_and_concise",
  "sender_name": "Ahmed Samir",
  "organization_name": "Kalima Tech",
  "include_signature": true,
  "signature": "Best regards,\n{{sender_name}}\n{{organization_name}}",
  "preferred_greeting": "Dear {{recipient_name}},",
  "auto_adjust_tone": true,
  "include_thread_context": true,
  "character_limit": 1000,
  "prompt_prefix": "You are an AI email assistant for {{organization_name}}. Keep messages professional, polite, and to the point.",
  "default_provider": "google"
}

---

Tools Supported

Tool	Description
send_email	Compose and send messages
read_email	Fetch and inspect messages
create_draft	Prepare messages
send_draft	Finalize and send
search_email	Query inbox with semantic filters
toggle_label	Modify categories/labels
archive_email	Clean up inbox
reply_email	Respond in thread context
delete_email	Remove messages
load_email_settings	View current email settings
update_email_settings	Update runtime email settings

---

Contributing

MailNet server is modular and extensible. To add a new provider, subclass the base client and implement the predefined hooks. PRs welcome!