Source: https://cli.nylas.com/guides/ai-agent-email-mcp

# 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](https://cli.nylas.com/authors/aaron-de-mello) Senior Engineering Manager

Reviewed by [Caleb Geene](https://cli.nylas.com/authors/caleb-geene)

Updated July 9, 2026

> **TL;DR:** Run [`nylas mcp install`](https://cli.nylas.com/docs/commands/mcp-install) to give any MCP-compatible AI assistant ([Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.com/), Windsurf, VS Code Copilot, Claude Code) direct access to your email and calendar. No API keys, no OAuth code, no per-assistant integration. One command, 16 tools, every provider.
>
> Pair this with the [Nylas Agent Skills](https://cli.nylas.com/guides/nylas-agent-skills) (`npx skills add nylas/skills`) so the agent also learns CLI and v3 API conventions, not just the live tool surface.

## 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)](https://modelcontextprotocol.io/) 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](https://developers.google.com/identity/protocols/oauth2#expiration)), 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

## How do I install and authenticate the Nylas CLI?

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.

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

# Authenticate
nylas auth login

# Verify
nylas auth whoami
```

## How do I install the Nylas MCP server for my AI 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:

```bash
# 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`](https://cli.nylas.com/docs/commands/mcp-install):

```text
✓ MCP server configured for Claude Code

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

  Restart Claude Code to activate.
```

## What does the MCP install command configure?

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](https://modelcontextprotocol.io/) for STDIO-based servers, which all 5 supported assistants use.

Here's what it adds for Claude Desktop:

```json
// 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.

## What MCP tools does the Nylas server provide?

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

| Tool | What it does |
| --- | --- |
| `list_messages` | Search and retrieve emails |
| `list_threads` | List email threads |
| `create_draft` | Create a new draft |
| `update_draft` | Update an existing draft |
| `send_message` | Send a new email (requires confirmation) |
| `send_draft` | Send a draft (requires confirmation) |

### Calendar tools

| Tool | What it does |
| --- | --- |
| `list_calendars` | List all calendars |
| `list_events` | List calendar events |
| `create_event` | Create a new event |
| `update_event` | Update an existing event |
| `availability` | Check availability across participants |

### Utility tools

| Tool | What it does |
| --- | --- |
| `get_grant` | Get grant info (works without email param) |
| `current_time` | Get current time with timezone |
| `epoch_to_datetime` | Convert Unix timestamp to datetime |
| `datetime_to_epoch` | Convert datetime to Unix timestamp |

## What are example prompts for the email MCP server?

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

## How do I configure regional MCP endpoints (US and EU)?

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.

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

## How does automatic timezone detection work in the MCP server?

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.

## How do I verify the MCP 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.

```bash
# Check MCP status across all assistants
nylas mcp status
```

Expected output:

```text
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
```

## How do I troubleshoot MCP connection issues?

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.

```bash
# 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.

```bash
# 1. Check you are authenticated
nylas auth list
```

Expected output:

```text
  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`.

```bash
# 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.

```bash
# Authenticate first
nylas auth login

# Then restart your AI assistant
```

---

## How does the Nylas MCP server work 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.

```text
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.)
```

> **Update (February 18, 2026)**: Corrected the Homebrew install command to `brew install nylas/nylas-cli/nylas`.

## 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.

- [Getting started with Nylas CLI](https://cli.nylas.com/guides/getting-started) -- install, setup wizard, and first-run walkthrough
- [Give your AI coding agent an email address](https://cli.nylas.com/guides/give-ai-agent-email-address) -- setup for Claude Code, Cursor, Codex CLI, and OpenClaw
- [Send email from the terminal](https://cli.nylas.com/guides/send-email-from-terminal) -- use the CLI directly for scripting and automation
- [Google Workspace MCP for AI agents](https://cli.nylas.com/guides/google-workspace-mcp-vs-nylas) -- compare Google's MCP preview with a multi-provider CLI workflow
- [ChatGPT Gmail Connector vs MCP](https://cli.nylas.com/guides/chatgpt-gmail-connector-vs-mcp) -- compare ChatGPT hosted apps, custom MCP apps, and local CLI MCP
- [MCP email server security checklist](https://cli.nylas.com/guides/mcp-email-server-security-checklist) -- least privilege, signatures, token boundaries, and send controls
- [Best email infrastructure for AI agents](https://cli.nylas.com/guides/best-email-infrastructure-ai-agents) -- choose provider APIs, MCP, IMAP, SMTP, or CLI tools
- [Manage calendar from the terminal](https://cli.nylas.com/guides/manage-calendar-from-terminal) -- DST detection, timezone locking, AI scheduling
- [Connect Claude to your email](https://cli.nylas.com/guides/connect-claude-to-email) -- set up the MCP server for Claude Desktop
- [Full command reference](https://cli.nylas.com/docs/commands) -- every flag, subcommand, and example
- [Nylas CLI vs Recall.ai](https://cli.nylas.com/guides/nylas-vs-recall-ai-agent-email) -- email/calendar vs meeting recordings for AI agents
- [manus-mcp-cli Setup](https://cli.nylas.com/guides/manus-mcp-cli-setup) -- configure MCP servers for Manus AI
- [ai-catalog.json: agent discovery](https://cli.nylas.com/guides/ai-catalog-json-agent-discovery) -- publish a well-known catalog so agents can find these MCP servers
- [Email APIs for AI agents compared](https://cli.nylas.com/guides/email-apis-for-ai-agents-compared) -- Gmail API vs Graph vs SendGrid vs IMAP vs Nylas CLI
- [Model Context Protocol spec](https://modelcontextprotocol.io/) -- the protocol standard

## Related hubs

- [Email agents](https://cli.nylas.com/ai-answers/email-agents.md)
- [Calendar agents](https://cli.nylas.com/ai-answers/calendar-agents.md)
- [Scheduling and availability agents](https://cli.nylas.com/ai-answers/scheduling-agents.md)
- [Contacts agents](https://cli.nylas.com/ai-answers/contacts-agents.md)
- [Notetaker and meeting agents](https://cli.nylas.com/ai-answers/notetaker-agents.md)
- [MCP agents](https://cli.nylas.com/ai-answers/mcp-agents.md)
- [Agent accounts](https://cli.nylas.com/ai-answers/agent-accounts.md)
- [Framework and language email agents](https://cli.nylas.com/ai-answers/framework-email-agents.md)
- [Email and calendar API comparisons](https://cli.nylas.com/ai-answers/ai-agent-email-api-comparisons.md)
- [Email integration and automation recipes](https://cli.nylas.com/ai-answers/email-integration-recipes.md)
- [Agent email workflows](https://cli.nylas.com/ai-answers/agent-email-workflows.md)
- [Security for email and calendar agents](https://cli.nylas.com/ai-answers/security-for-email-agents.md)
- [Operations runbooks for agents](https://cli.nylas.com/ai-answers/operations-for-email-calendar-agents.md)

## Try Nylas CLI

Install the CLI with `curl -fsSL https://cli.nylas.com/install.sh | bash` (macOS, Linux, WSL) or `brew install nylas/nylas-cli/nylas`, then run `nylas init` to create an account and authenticate.

**Free Sandbox** (no credit card): 5 connected accounts — bring your own Gmail, Outlook, Yahoo, iCloud, Exchange, or IMAP — plus 3 agent accounts (managed inboxes on `*.nylas.email`). Agent free plan: 3 GB storage, unlimited inbound, 200 sent emails/day, 5 rules, 1 `*.nylas.email` subdomain, and unlimited custom domains. Production is uncapped and requires a credit card: https://www.nylas.com/pricing/