Guide

Email MCP Server for AI Agents

The Model Context Protocol (MCP) lets AI assistants interact with external tools through a standardized interface. The Nylas CLI includes a built-in email MCP server that gives any MCP-compatible assistant access to email and calendar across Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP -- without writing integration code or managing API keys in multiple places.

Written by Aaron de Mello Senior Engineering Manager

Reviewed by Caleb Geene

Verified — CLI 3.1.1 · Gmail, Outlook · last tested April 11, 2026

What is an email MCP server?

An email MCP server is a tool server that lets an AI assistant call mailbox actions through Model Context Protocol instead of scraping a web inbox or handling raw OAuth code. A useful email MCP server should expose separate tools for search, read, draft, send, and calendar context so the agent can request the smallest action needed.

For searches like mcp server for mail, the practical question is whether the server is read-only, write-capable, local, hosted, or tied to one provider. The CLI MCP path is local and provider-neutral: the assistant starts nylas mcp serve, and the same tool surface works across Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP.

Why MCP instead of custom integrations?

Model Context Protocol (MCP) is a standardized interface that lets AI assistants call external tools without custom glue code. Instead of building a separate integration for each assistant, you run one MCP server and every compatible client — Claude, Cursor, Windsurf, VS Code Copilot — connects through the same protocol with the same 16 tools.

Before MCP, giving an AI agent email access meant managing OAuth tokens (Gmail access tokens expire every 3,600 seconds), handling refresh flows, and writing provider-specific code for each of the 6 major email providers. A typical custom integration requires 200-400 lines of OAuth and API client code per provider. The Nylas CLI eliminates that by acting as the MCP server itself:

  • Injects your authenticated credentials automatically
  • Detects your system timezone so all times display consistently
  • Routes requests to the correct regional endpoint (US or EU)
  • Handles grant lookups without requiring you to type your email

1. Install and authenticate

The Nylas CLI installs via Homebrew on macOS and Linux. After installing, you authenticate with nylas auth login, which opens a browser-based OAuth flow and stores your grant locally. The whole process takes under 2 minutes. Run nylas auth whoami to confirm the grant is valid before proceeding.

# Install the CLI
brew install nylas/nylas-cli/nylas

# Authenticate
nylas auth login

# Verify
nylas auth whoami

2. Install MCP for your assistant

The nylas mcp install command is the single entry point for connecting any supported AI assistant to your email and calendar. It auto-detects which assistants are installed on your machine, writes the correct JSON config for each one, and sets up tool permissions where needed. The command supports 5 assistants: Claude Desktop, Claude Code, Cursor, Windsurf, and VS Code Copilot.

Run it interactively or pass --assistant to target a specific client:

# Interactive -- detects installed assistants
nylas mcp install

# Or specify directly
nylas mcp install --assistant claude-desktop   # Claude Desktop
nylas mcp install --assistant claude-code       # Claude Code (also sets permissions)
nylas mcp install --assistant cursor            # Cursor
nylas mcp install --assistant windsurf          # Windsurf
nylas mcp install --assistant vscode            # VS Code (project-level)

# Install for all detected assistants at once
nylas mcp install --all

Example output after running nylas mcp install --assistant claude-code:

✓ MCP server configured for Claude Code

  Binary: /opt/homebrew/bin/nylas
  Command: mcp serve
  Config: /home/dev/.claude.json

  Restart Claude Code to activate.

3. What gets configured

The MCP install command writes a JSON block into each assistant's native configuration file. This block tells the assistant where to find the Nylas binary and what arguments to pass when spawning the MCP server process. The config format follows the MCP specification for STDIO-based servers, which all 5 supported assistants use.

Here's what it adds for Claude Desktop:

// Example: Claude Desktop config
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "nylas": {
      "command": "/opt/homebrew/bin/nylas",
      "args": ["mcp", "serve"]
    }
  }
}

For Claude Code, it also adds mcp__nylas__* to ~/.claude/settings.json so all Nylas tools are pre-approved without interactive prompts.

4. Available MCP tools

The Nylas MCP server exposes 16 tools split across email, calendar, and utility categories. These tools map directly to the Nylas API v3 endpoints but are wrapped with automatic credential injection and timezone handling. Every tool works across all 6 supported providers — Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP — without provider-specific configuration.

Email tools

ToolWhat it does
list_messagesSearch and retrieve emails
list_threadsList email threads
create_draftCreate a new draft
update_draftUpdate an existing draft
send_messageSend a new email (requires confirmation)
send_draftSend a draft (requires confirmation)

Calendar tools

ToolWhat it does
list_calendarsList all calendars
list_eventsList calendar events
create_eventCreate a new event
update_eventUpdate an existing event
availabilityCheck availability across participants

Utility tools

ToolWhat it does
get_grantGet grant info (works without email param)
current_timeGet current time with timezone
epoch_to_datetimeConvert Unix timestamp to datetime
datetime_to_epochConvert datetime to Unix timestamp

5. Example prompts for your AI assistant

MCP tools are invoked through natural language — you don't write JSON-RPC calls or function signatures. The assistant maps your request to one or more of the 16 available tools automatically. Below are 5 common patterns that combine tool calls for real workflows.

  • "Summarize my unread emails from today" -- uses list_messages
  • "Draft a reply to the email from Sarah about the budget" -- uses list_messages + create_draft
  • "Schedule a 30-minute meeting with alice@company.com next Tuesday at 2pm" -- uses create_event
  • "Check if I am free Thursday afternoon" -- uses availability
  • "Find all emails about the Q4 contract and summarize the key decisions" -- uses list_messages with search

6. Regional endpoints

Nylas operates 2 regional MCP endpoints: mcp.us.nylas.com for the US region and mcp.eu.nylas.com for the EU region. The MCP proxy reads your region setting from ~/.config/nylas/config.yaml at startup and routes all API traffic to the matching endpoint. This matters for data residency — EU grants stay in the EU region.

# ~/.config/nylas/config.yaml
region: us   # default -- uses mcp.us.nylas.com
# region: eu # uses mcp.eu.nylas.com

7. Automatic timezone detection

Timezone detection is a feature of the Nylas MCP proxy that reads your system's local timezone at startup and injects it into the server instructions sent to the assistant. Without this, AI calendar tools default to UTC, which causes events to land hours off for the 75% of the world's population outside the UTC+0 zone. The proxy eliminates this mismatch automatically.

  • All email timestamps display in your local time
  • Calendar events are created in your timezone by default
  • No more mixing UTC, EST, and PST in the same conversation
If times are displaying incorrectly, restart your AI assistant after installing MCP. The timezone is detected at startup.

8. Verify the installation

The nylas mcp status command checks all 5 supported assistants in one pass and reports which ones have the Nylas MCP server configured. It reads each assistant's config file, checks for the nylas server entry, and flags any that are available but not yet connected. Run it after installing to confirm everything is wired up.

# Check MCP status across all assistants
nylas mcp status

Expected output:

MCP Installation Status:

  ✓ Claude Code       configured    /home/dev/.claude.json
  ○ Claude Desktop    not configured
  ○ Cursor            not configured
  ○ VS Code           not configured
  - Windsurf          application not installed

Legend:
  ✓ Nylas MCP configured
  ○ Available but not configured
  - Not available

Troubleshooting

Troubleshooting MCP connections usually comes down to 3 issues: missing permissions, expired authentication, or a stale server process. The fixes below cover the most common failures reported across Claude Code, Cursor, and Windsurf. Most resolve in under 60 seconds.

Permission denied errors (Claude Code)

Claude Code requires pre-approved tool permissions in ~/.claude/settings.json. If the MCP install didn't write the mcp__nylas__* entries, tool calls will fail with a permission error. Re-running the install command fixes this automatically by adding the missing permission entries.

# Re-run install to fix permissions automatically
nylas mcp install --assistant claude-code

MCP server not responding

A non-responsive MCP server usually means the CLI isn't authenticated or the binary path in the config doesn't match where the CLI is actually installed. Start by checking your active grants with nylas auth list, then test the server manually with a raw JSON-RPC initialize call.

# 1. Check you are authenticated
nylas auth list

Expected output:

  GRANT ID                                EMAIL                     PROVIDER      STATUS        DEFAULT
  d3f4a5b6-c7d8-9e0f-a1b2-c3d4e5f6g7h8   dev@example.com           Google        ✓ valid       ✓
  e4f5a6b7-d8e9-0f1a-b2c3-d4e5f6a7b8c9   work@example.com          Microsoft     ✓ valid

The manual test below sends a JSON-RPC initialize request directly to the MCP server over STDIO. If it returns a valid response, the server binary is working and the issue is in the assistant's config. If it errors, check the binary path with which nylas.

# 2. Test the server manually
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | nylas mcp serve

# 3. Verify the binary path
which nylas

No authenticated grants found

This error means the CLI has no stored OAuth grants. Run nylas auth login to start the browser-based OAuth flow, which stores the grant in ~/.config/nylas/. After authenticating, restart your AI assistant so the MCP server picks up the new credentials on its next startup.

# Authenticate first
nylas auth login

# Then restart your AI assistant

How it works under the hood

The Nylas MCP architecture has 3 layers: the AI assistant communicates with the local CLI proxy over STDIO using JSON-RPC, the proxy adds credentials and routes the request over HTTPS to the Nylas MCP server (mcp.us.nylas.com or mcp.eu.nylas.com), and the server calls the Nylas API v3 which connects to the underlying email or calendar provider. This keeps all OAuth tokens local to your machine — they never pass through the assistant.

AI Assistant (Claude / Cursor / VS Code)
    |
    | STDIO (JSON-RPC)
    v
Nylas CLI MCP Proxy  (nylas mcp serve)
    - Reads region from config
    - Injects credentials automatically
    - Detects timezone
    - Handles local get_grant
    |
    | HTTPS
    v
Nylas MCP Server  (mcp.us.nylas.com or mcp.eu.nylas.com)
    |
    | Nylas API v3
    v
Email / Calendar Providers  (Google, Microsoft, etc.)

Next steps

With MCP configured, your AI assistant can read, draft, and send email plus create and query calendar events across all 6 supported providers. The guides below cover adjacent workflows — from direct CLI scripting to comparing the CLI against other email APIs for AI agents.