convez.ai
MCP Server
ftaricano

mcp-outlook

ftaricano/mcp-outlook

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server for Microsoft Outlook / Exchange via Microsoft Graph API — 40 tools, client-credentials auth, no Mail.Send required for drafts

Instalação

$npx convez-ai ftaricano/mcp-outlook

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 3 dias
Versão
v2.3.0
Issues abertas
9
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

mcp-outlook

License: MIT Node.js CI MCP

MCP server for Microsoft Outlook / Exchange via the Microsoft Graph API. Exposes 40 tools over stdio — list, send, draft, search, organize, batch-operate, and handle attachments including large-file hybrid flows that bypass MCP token limits.

Works with any MCP-compatible client (Claude Desktop, Cursor, custom agents, etc.). Authenticates via Azure AD client-credentials (no user login required).

MetricValue
Tools40
Tests183 passing
Node≥ 20
MCP SDK^1.29.0
LicenseMIT

Requirements

  • Node.js 20 or 22
  • Azure AD app registration with Application permissions:
    • Mail.ReadWrite — required for all read/draft/folder operations
    • Mail.Send — required only if you call send_email or reply_to_email
    • User.Read.All — optional, only for list_users
  • Admin consent granted in the Azure Portal

Install

git clone https://github.com/ftaricano/mcp-outlook.git
cd mcp-outlook
npm install
npm run build

Configure

Four required values feed both the server and the CLI:

VariableRequiredDescription
MICROSOFT_GRAPH_CLIENT_IDyesAzure AD application (client) UUID
MICROSOFT_GRAPH_CLIENT_SECRETyesClient secret value
MICROSOFT_GRAPH_TENANT_IDyesAzure AD tenant UUID
TARGET_USER_EMAILyes*Mailbox to operate on. Strongly recommended — omitting it causes runtime errors from Graph rather than a clean startup failure.
LOG_LEVELnoerror / warn / info (default) / debug
OUTLOOK_KEYCHAIN_PREFIXnomacOS Keychain service prefix. Default: mcp-outlook.
DOWNLOAD_DIRnoAbsolute write root. All attachment downloads land here; everything else is rejected. Default: ~/Downloads/mcp-outlook-attachments.
MCP_EMAIL_UPLOAD_DIRSnoColon-separated read allowlist for send_email_with_file / encode_file_for_attachment. Anything outside — including symlinks pointing out and files in ~/.ssh, ~/.aws, *.env, *.pem, etc. — is rejected. Defaults to DOWNLOAD_DIR.
MAX_ATTACHMENT_MBnoAttachment size cap (default: 25)

Resolution order (first hit wins): process.env → <repo>/.env (if present) → macOS Keychain (security find-generic-password -s "<prefix>::<VARIABLE>" -a "$USER"). On macOS, the default prefix is mcp-outlook; set OUTLOOK_KEYCHAIN_PREFIX if you want a different namespace.

To populate the Keychain:

security add-generic-password -U -s "mcp-outlook::MICROSOFT_GRAPH_CLIENT_ID"     -a "$USER" -w '<uuid>'
security add-generic-password -U -s "mcp-outlook::MICROSOFT_GRAPH_CLIENT_SECRET" -a "$USER" -w '<secret>'
security add-generic-password -U -s "mcp-outlook::MICROSOFT_GRAPH_TENANT_ID"     -a "$USER" -w '<uuid>'
security add-generic-password -U -s "mcp-outlook::TARGET_USER_EMAIL"             -a "$USER" -w 'user@example.com'

For multi-account CLI setups, pass an alternative .env via --env-file or $OUTLOOK_ENV_FILE. Those explicit files override existing credential variables for the one-shot CLI process; the default <repo>/.env is only a missing-value fallback.

After setting permissions in Azure AD, click Grant admin consent — without this step every call returns 403.

Quickstart

Claude Desktop / Cursor

Add to your MCP client config:

{
  "mcpServers": {
    "outlook": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-outlook/dist/index.js"],
      "env": {
        "MICROSOFT_GRAPH_CLIENT_ID": "your-client-id",
        "MICROSOFT_GRAPH_CLIENT_SECRET": "your-client-secret",
        "MICROSOFT_GRAPH_TENANT_ID": "your-tenant-id",
        "TARGET_USER_EMAIL": "user@example.com"
      }
    }
  }
}

Direct (stdio)

npm start

outlook CLI (one-shot calls)

The package ships with a standalone CLI — ./scripts/outlook.js, registered as the outlook bin — that spawns the server, runs a single MCP request, and exits. Useful for scripts, cron, smoke-testing a tool, or inspecting a schema without wiring up an MCP client.

# Discover
outlook list                          # all 40 tools with descriptions
outlook schema list_emails            # input schema for a single tool

# Call with flags
outlook list_emails --limit=5 --folder=inbox
outlook create_draft --to='["a@b.com"]' --subject="Hi" --body="Hello"

# Call with raw JSON (useful for arrays/objects)
outlook batch_mark_as_read --json '{"emailIds":["id1","id2"]}'

# Flags: --env-file <path>, --timeout <ms>, --compact, --help

CLI credentials resolve in this order: --env-file <path> → $OUTLOOK_ENV_FILE → existing env vars → <repo>/.env for missing values → macOS Keychain. Explicit env files override existing credential variables for this one-shot process; the default repo .env does not.

Docker

docker build -t mcp-outlook .
docker run --rm -i --env-file .env mcp-outlook

Tools

40 tools across 6 categories:

CategoryTools
Emaillist_emails, send_email, create_draft, reply_to_email, mark_as_read, mark_as_unread, delete_email, summarize_email, summarize_emails_batch, list_users
Attachmentslist_attachments, download_attachment, download_attachment_to_file, download_all_attachments, list_downloaded_files, get_download_directory_info, cleanup_old_downloads, export_email_as_attachment, encode_file_for_attachment
Hybrid (large-file)send_email_from_attachment, send_email_with_file
Folderslist_folders, create_folder, move_emails_to_folder, copy_emails_to_folder, delete_folder, get_folder_stats, organize_emails_by_rules
Searchadvanced_search, search_by_sender_domain, search_by_attachment_type, find_duplicate_emails, search_by_size, saved_searches
Batchbatch_mark_as_read, batch_mark_as_unread, batch_delete_emails, batch_move_emails, batch_download_attachments, email_cleanup_wizard

Hybrid functions

send_email_from_attachment and send_email_with_file solve a fundamental MCP limitation: large Base64 payloads overflow the protocol's token budget. These tools download/read the file directly on disk, then call the Graph API — no Base64 transfer through MCP at all.

create_draft vs send_email

create_draft only requires Mail.ReadWrite. Use it when your tenant policy blocks Mail.Send (common in restrictive enterprise environments). The draft lands in the Drafts folder; open Outlook to review and send.

Architecture

src/
  config/env.ts             # zod-validated env — fails fast on bad credentials
  auth/graphAuth.ts         # MSAL client-credentials token provider (auto-refresh)
  services/emailService.ts  # Microsoft Graph wrapper with response caching + batch helpers
  schemas/toolSchemas.ts    # zod schemas for all 40 tool inputs
  handlers/*.ts             # one handler class per domain (email, folder, search…)
  handlers/HandlerRegistry  # zod validation + dispatch
  logging/logger.ts         # stderr JSON logger
  templates/                # HTML email templates (4 themes)
  utils/                    # file manager, attachment validator, secret redaction

Runtime flow:

  1. loadEnv() validates credentials via zod on startup — bad config exits immediately with a clear message.
  2. GraphAuthProvider lazily acquires tokens and refreshes 60 s before expiry.
  3. MCP requests hit HandlerRegistry.handleTool(name, args) → zod validation → domain handler.
  4. Handlers call EmailService, which wraps Graph with response caching and batch helpers. Retry/backoff on 429 (honoring Retry-After) comes from the Graph SDK's default middleware, not a custom limiter.

Develop

CommandPurpose
npm run buildTypeScript → dist/
npm run typechecktsc --noEmit
npm run lint / npm run lint:fixESLint
npm run format / npm run format:checkPrettier
npm testVitest unit tests
npm run test:coverageVitest with coverage thresholds
npm run smokeProtocol smoke — verify tools/list returns 40 entries
npm run audit:prodAudit runtime deps only

CI runs lint + typecheck + tests + smoke on Node 20 and 22.

Live integration smoke tests (require Graph credentials in env):

node scripts/live-readonly-smoke.js   # 20 read-only + dry-run tools
node scripts/live-writes-smoke.js     # 9 write-path tools (self-contained, safe)

Troubleshooting

403 / "Insufficient privileges" — Admin consent not granted. Go to Azure Portal → your app → API permissions → Grant admin consent.

send_email returns 403 but create_draft works — Your tenant policy blocks Mail.Send at the application level. Use create_draft instead.

Attachments arrive with 0 KB — Base64 payload too large for the MCP transport. Use send_email_from_attachment or send_email_with_file (hybrid functions).

delete_email returns 404 after move_emails_to_folder — Microsoft Graph issues a new message ID on move. The handler now returns the new ID in its output; re-read it before deleting.

Rate limiting (429) — Reduce maxConcurrent in batch operations. The Graph SDK's retry middleware backs off automatically (honoring Retry-After), but very high concurrency can still hit Graph throttle limits.

Security

This server handles Azure AD client secrets with broad mailbox access, and it is driven by an LLM that sees untrusted email bodies. Treat every tool call as potentially attacker-influenced.

Filesystem allowlist (pathGuard) — send_email_with_file, encode_file_for_attachment, and all attachment download paths go through a central allowlist (src/security/pathGuard.ts):

  • Writes are confined to DOWNLOAD_DIR.
  • Reads are confined to MCP_EMAIL_UPLOAD_DIRS (defaults to DOWNLOAD_DIR).
  • Symlinks, .. traversal, NUL bytes, and files in secret-bearing locations (~/.ssh, ~/.aws, ~/.gnupg, .env*, *.pem, *.key, *.p12, *.pfx, credentials.json, id_rsa*, etc.) are rejected before the file is read.

Without this guard, an attacker who controls an email body could instruct the agent to attach ~/.ssh/id_rsa to an outbound email. The guard blocks that class of confused-deputy attack at the boundary.

Keep these practices:

  • Never commit .env — it is in .gitignore
  • Never commit *.log or *.jsonl files — also in .gitignore
  • Store secrets in your OS keychain or a secrets manager, not in plaintext files
  • Rotate the client secret in Azure AD immediately if it is ever exposed
  • Set MCP_EMAIL_UPLOAD_DIRS to the minimum set of directories the server actually needs to read. Do not set it to $HOME or /.
  • Scope Mail.Send only if you need outbound email — Mail.ReadWrite alone is sufficient for drafts, search, and folder management
  • User-supplied HTML template fields are escaped before rendering. If you intentionally need trusted HTML, add an explicit sanitizer/allowlist instead of bypassing the template engine.

Report vulnerabilities privately through GitHub Security Advisories. See SECURITY.md.

Known limitations

  • TARGET_USER_EMAIL is optional in the schema for delegated /me experiments, but client-credentials deployments should set it. Microsoft Graph application permissions do not infer a mailbox.
  • The outlook CLI has a few tracked edge cases around numeric search flags, sender filtering, and download target paths. See issue #30; use --json for numeric search terms until that issue is closed.

Contributing

npm run build && npm test && npm run smoke

Pre-PR checklist: build passes, lint clean, all tests green, smoke returns 40 tools.

Open an issue before submitting large changes.

Development workflow

For small fixes, keep the PR focused and include the command output from the pre-PR checklist. For larger changes, open an issue first and describe the affected tool contracts, Graph permissions, security impact, and manual smoke coverage.

Security-sensitive paths deserve extra review: src/security/, credential loading, Graph permission scopes, attachment handling, template rendering, and anything that reads from or writes to the local filesystem.

License

MIT

Ver o original no GitHub

Bom para

Relacionados