Source: https://cli.nylas.com/guides/mcp-email-server-setup

# Set Up an MCP Email Server in 5 Minutes

The Model Context Protocol (MCP) hit 97 million monthly SDK downloads by March 2026. An MCP email server gives AI agents direct access to email, calendar, and contacts without custom integration code. This guide walks through installing, configuring, and verifying the Nylas MCP email server for Claude Code, Cursor, Windsurf, VS Code Copilot, and Claude Desktop.

Written by [Qasim Muhammad](https://cli.nylas.com/authors/qasim-muhammad) Staff SRE

Updated May 21, 2026

> **TL;DR:** Run [`nylas mcp install --assistant claude-code`](https://cli.nylas.com/docs/commands/mcp-install) to connect an AI agent to your email and calendar through MCP. The server exposes 16 tools across 6 providers. Setup takes under 60 seconds.

Command references used in this guide: [`nylas mcp install`](https://cli.nylas.com/docs/commands/mcp-install) for registering the server, [`nylas mcp serve`](https://cli.nylas.com/docs/commands/mcp-serve) for starting the STDIO server, [`nylas mcp status`](https://cli.nylas.com/docs/commands/mcp-status) for verifying configuration, [`nylas auth login`](https://cli.nylas.com/docs/commands/auth-login) for OAuth authentication, and [`nylas auth whoami`](https://cli.nylas.com/docs/commands/auth-whoami) for checking grant status.

## What is an MCP email server?

An MCP email server is a local process that exposes email operations (send, read, search, draft) and calendar operations (list, create, check availability) as tools an AI agent can call through the [Model Context Protocol](https://modelcontextprotocol.io/). The agent sends JSON-RPC tool-use requests over STDIO; the server translates them into email API calls and returns structured results. No custom glue code, no per-assistant integration.

MCP was created by Anthropic in November 2024 and [donated to the Linux Foundation](https://www.anthropic.com/news/donating-the-model-context-protocol-and-establishing-of-the-agentic-ai-foundation) in December 2025 with OpenAI, Google, and Microsoft as co-sponsors. By March 2026, the protocol reached 97 million monthly SDK downloads and the public server registry listed over 9,400 servers. Every major AI coding tool now supports it natively: Claude Code, Cursor, Windsurf, VS Code Copilot, and JetBrains AI Assistant.

## How do I install the Nylas MCP email server?

The Nylas CLI includes a built-in MCP email server that connects AI agents to Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP accounts. Install the CLI via Homebrew, authenticate with OAuth, and register the MCP server with your AI tool. The entire process takes under 60 seconds if you already have Homebrew installed. For other install methods (shell script, PowerShell, Go), see the [getting started guide](https://cli.nylas.com/guides/getting-started).

The install command below adds the CLI and authenticates your email account. The OAuth flow opens a browser window, stores the grant locally in `~/.config/nylas/`, and handles token refresh automatically. Tokens refresh every 3,600 seconds without manual intervention.

```bash
# Install the CLI (macOS / Linux)
brew install nylas/nylas-cli/nylas

# Authenticate your email account
nylas auth login

# Confirm the grant is active
nylas auth whoami
```

Once authenticated, register the MCP server for your AI tool with a single command. The [`nylas mcp install`](https://cli.nylas.com/docs/commands/mcp-install) command detects which assistants are installed, writes the correct JSON config, and sets up tool permissions where the assistant requires them (Claude Code needs explicit permission entries).

```bash
# Register the MCP server (interactive -- detects installed tools)
nylas mcp install

# Or target a specific tool
nylas mcp install --assistant claude-code
nylas mcp install --assistant cursor
nylas mcp install --assistant windsurf
nylas mcp install --assistant vscode
nylas mcp install --assistant claude-desktop

# Or install for all detected tools at once
nylas mcp install --all
```

## How do I configure MCP for each AI tool?

The `nylas mcp install` command writes the correct config automatically, but understanding what it writes helps with debugging. Every tool uses the same JSON block — it points to the Nylas binary and passes `mcp serve` as the startup argument. The server communicates over STDIO using JSON-RPC, which all 5 supported tools expect. Roughly 78% of enterprise AI teams run at least one MCP-backed agent in production as of April 2026.

```json
// The config block is identical for every tool — only the file path differs
{
  "mcpServers": {
    "nylas": {
      "command": "/opt/homebrew/bin/nylas",
      "args": ["mcp", "serve"]
    }
  }
}
```

Place that block in the config file for your tool. Claude Code also needs `mcp__nylas__*` added to `~/.claude/settings.json` so all 16 tools are pre-approved without interactive prompts — `nylas mcp install --assistant claude-code` handles both files.

| Tool | Config file | Scope |
| --- | --- | --- |
| **Claude Code** | `~/.claude.json` | Global |
| **Cursor** | `.cursor/mcp.json` | Project (auto-discovers 16 tools in ~2 seconds) |
| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | Global (restart after editing) |
| **VS Code Copilot** | `.vscode/mcp.json` | Project |
| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` | Global (first MCP client, Nov 2024) |

For per-tool setup walkthroughs with screenshots and hosted MCP server alternatives, see the [give your AI agent an email address](https://cli.nylas.com/guides/give-ai-agent-email-address) guide.

## What email tools does the MCP server expose?

The Nylas MCP server exposes 16 tools across email, calendar, and utility categories. These tools map to [Nylas API v3](https://developer.nylas.com/docs/api/v3/) endpoints but include automatic credential injection, timezone detection, and grant lookup. Every tool works across all 6 supported providers without provider-specific configuration. The agent discovers all 16 tools at startup through MCP's built-in tool discovery protocol.

### Email tools (6)

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

### Calendar tools (5)

| Tool | What it does |
| --- | --- |
| `list_calendars` | List all calendars on the account |
| `list_events` | Query events with date and keyword filters |
| `create_event` | Create a calendar event with attendees |
| `update_event` | Modify an existing event |
| `availability` | Check free/busy across participants |

### Utility tools (5)

| Tool | What it does |
| --- | --- |
| `get_grant` | Return grant info without requiring the email parameter |
| `current_time` | Return current time with the detected system timezone |
| `epoch_to_datetime` | Convert a Unix timestamp to a human-readable datetime |
| `datetime_to_epoch` | Convert a datetime string to Unix epoch seconds |
| `list_contacts` | List contacts from the address book |

Here's what a tool call looks like in practice. The agent sends a JSON-RPC request naming the tool and parameters. The MCP server handles authentication, calls the Nylas API, and returns the result. The round-trip takes under 500ms for most operations.

```json
// Agent sends:
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_messages",
    "arguments": {
      "limit": 5,
      "subject": "quarterly report"
    }
  }
}

// Server returns structured email data:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 3 messages matching 'quarterly report'..."
      }
    ]
  }
}
```

## How do I verify the MCP server works?

The [`nylas mcp status`](https://cli.nylas.com/docs/commands/mcp-status) command checks all 5 supported AI tools in a single pass and reports which ones have the Nylas MCP server configured. It reads each tool's config file, verifies the `nylas` server entry exists, and flags tools that are installed but not yet connected. Run it immediately after `nylas mcp install` to confirm the setup.

```bash
nylas mcp status
```

Expected output:

```text
MCP Installation Status:

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

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

For an end-to-end test, open your AI tool and ask it something that exercises the MCP server. A simple prompt like "list my 3 most recent emails" will call `list_messages` and confirm the full chain works: STDIO transport, credential injection, API call, and response parsing. If the tool returns email subjects, the server is working.

### Common errors and fixes

Most MCP server issues come down to 3 things: missing authentication, wrong binary path, or stale config. These fixes resolve 90% of reported problems in under 60 seconds.

| Error | Cause | Fix |
| --- | --- | --- |
| `No authenticated grants found` | CLI isn't authenticated | Run `nylas auth login`, then restart your AI tool |
| `Permission denied` (Claude Code) | Missing tool permissions in settings.json | Re-run `nylas mcp install --assistant claude-code` |
| MCP server not responding | Binary path mismatch in config | Run `which nylas` and update the `command` field in the config file |
| Tools not appearing | AI tool needs a restart after config change | Restart the AI tool so it spawns the MCP server process |

## How does MCP compare to direct API calls?

MCP and direct API calls solve different problems. MCP gives AI agents a standardized way to discover and call tools across services, while direct API calls with [agent skills](https://cli.nylas.com/guides/nylas-agent-skills) are faster and use fewer tokens per operation. According to benchmarks published by Toolradar in 2026, direct API calls are 33% more token-efficient and 30x faster for batch operations. The best-performing agents use both: MCP for interactive multi-service discovery, direct API for hot paths and bulk work.

| Factor | MCP | Direct API |
| --- | --- | --- |
| Setup time | Under 60 seconds (`nylas mcp install`) | 5-15 minutes (API keys, SDK, code) |
| Token efficiency | Baseline (tool schemas in context) | 33% fewer tokens per call |
| Batch operations | Sequential tool calls | 30x faster with parallel requests |
| Provider coverage | 6 providers, 16 tools, auto-discovered | Same 6 providers, full API surface |
| Tool discovery | Automatic at startup | Requires skill files or documentation |
| Best for | Interactive agent workflows, multi-service | High-volume pipelines, cost-sensitive apps |

For a deeper comparison with architecture diagrams and benchmark data, see the full [MCP vs API for AI agents](https://cli.nylas.com/guides/mcp-vs-api-ai-agents) guide.

## Next steps

- [Full command reference](https://cli.nylas.com/docs/commands) -- every flag, subcommand, and example
- [MCP vs API for AI agents](https://cli.nylas.com/guides/mcp-vs-api-ai-agents) -- benchmarks and a decision matrix for choosing the right integration approach
- [Email MCP server for AI agents](https://cli.nylas.com/guides/ai-agent-email-mcp) -- deeper dive into tools, architecture, regional endpoints, and example prompts
- [MCP email server security checklist](https://cli.nylas.com/guides/mcp-email-server-security-checklist) -- least privilege, token boundaries, and write-action controls
- [Give your AI coding agent an email address](https://cli.nylas.com/guides/give-ai-agent-email-address) -- per-tool setup for Claude Code, Cursor, Codex CLI, and Windsurf
- [Getting started with Nylas CLI](https://cli.nylas.com/guides/getting-started) -- install methods, setup wizard, and first-run walkthrough
- [Model Context Protocol specification](https://modelcontextprotocol.io/) -- the protocol standard maintained by the Linux Foundation