# How to use Nylas MCP with Claude Code

Source: https://developer.nylas.com/docs/cookbook/ai/mcp/claude-code/

[Claude Code](https://code.claude.com/) is Anthropic's AI coding agent for the terminal. By connecting it to the Nylas MCP server, you give Claude direct access to [email](/docs/v3/email/), [calendar](/docs/v3/calendar/), and [contacts](/docs/v3/email/contacts/) data across Gmail, Outlook, Exchange, and any IMAP provider, all without leaving your development workflow.

The connection uses streamable HTTP with Bearer token authentication. You can set it up in about two minutes with a single CLI command or a short JSON config file.

## Why connect Claude Code to Nylas?

Without MCP, using email or calendar data in a coding session means switching to a browser, copying IDs or timestamps, and pasting them back into your terminal. Connecting Claude Code to Nylas through MCP removes that friction:

- **Inline access to real data.** Ask Claude to look up a message, check a calendar, or search contacts without leaving your session.
- **Multi-provider support.** One connection covers [Gmail](/docs/provider-guides/google/), [Outlook](/docs/provider-guides/microsoft/), [Yahoo](/docs/provider-guides/yahoo-authentication/), [iCloud](/docs/provider-guides/icloud/), [Exchange](/docs/provider-guides/imap/), and any IMAP server.
- **Two-step send safety.** The MCP server requires a confirmation hash before sending any email, so Claude can never send a message without you seeing a confirmation step first.
- **No SDK or API code needed.** Claude calls the Nylas API through MCP tools directly; you don't need to write integration code.

## Before you begin


Before you start, make sure you have:

1. **A Nylas account.** Sign up at [dashboard-v3.nylas.com](https://dashboard-v3.nylas.com) if you don't have one.
2. **A Nylas application.** Go to All apps > Create new app > Choose your region (US or EU).
3. **An API key.** Go to API Keys > Create new key.
4. **At least one connected grant.** Go to Grants > Add Account and authenticate an email account (Gmail, Outlook, etc.).

> **Info:** 
> **New to Nylas?** The [Getting started guide](/docs/v3/getting-started/) walks through account setup, application creation, and connecting your first grant in detail.


You also need **Claude Code** installed. If you haven't set it up yet, follow the [Claude Code installation guide](https://code.claude.com/docs/en/quickstart).

## Set up the Nylas MCP server

You can connect Claude Code to Nylas using the CLI or by editing a configuration file directly. The CLI is fastest for getting started; the config file is better for sharing setup across a team.

### Option 1: Add with the CLI

Run this command in your terminal:

```bash
claude mcp add --transport http nylas \
  --header "Authorization: Bearer YOUR_NYLAS_API_KEY" \
  https://mcp.us.nylas.com
```

Replace `YOUR_NYLAS_API_KEY` with the API key from your [Nylas Dashboard](https://dashboard-v3.nylas.com). If your application is in the EU region, use `https://mcp.eu.nylas.com` instead.

By default, this adds the server to your **local** scope (available only to you in the current project). Use `--scope user` to make it available across all your projects.

### Option 2: Add with JSON config

You can also use `claude mcp add-json` for more control over the configuration:

```bash
claude mcp add-json nylas '{"type":"http","url":"https://mcp.us.nylas.com","headers":{"Authorization":"Bearer YOUR_NYLAS_API_KEY"}}'
```

> **Warn:** 
> **Do not commit API keys to version control.** The `claude mcp add` commands above store your resolved API key in the config. If you use `--scope project`, the key is written to `.mcp.json` in your project root. Add `.mcp.json` to your `.gitignore` or have each team member run the setup command locally with their own key.

### Verify the connection

Restart Claude Code (or start a new session), then check that the Nylas server is connected:

```bash
claude mcp list
```

You should see `nylas` listed with its URL. Inside Claude Code, you can also run `/mcp` to see all connected servers and their status.

## Example workflows

Once connected, you can interact with email and calendar data using natural language. Claude translates your requests into MCP tool calls automatically.

### Triage your inbox

```
Show me unread emails from the last 24 hours and summarize them by priority
```

Claude calls `get_grant` to resolve your account, then `list_messages` with date and unread filters. It groups the results by sender or urgency and returns a summary you can act on. This is particularly useful during morning standup prep or when catching up after time off.

### Check your schedule

```
What meetings do I have tomorrow? Flag any conflicts.
```

Claude uses `list_calendars` to find your calendars, then `list_events` with a date range filter. It analyzes the results for overlapping time slots and highlights back-to-back meetings. This works across Google Calendar, Outlook, and any other connected provider.

### Draft a reply

```
Draft a reply to the last email from sarah@example.com saying I'll review the proposal by Friday
```

Claude finds the relevant message with `list_messages`, then calls `create_draft` with the original thread ID to keep the reply in the same conversation. The draft lands in your email client for review. Nothing is sent until you explicitly send from your email client or ask Claude to send it (which triggers the two-step confirmation).

### Schedule a meeting

```
Create a 30-minute meeting with alex@example.com tomorrow at 2pm called "API Review"
```

Claude calls `create_event` with the title, participants, start time, and duration. For better scheduling, you can ask Claude to check availability first:

```
Check if alex@example.com is free tomorrow at 2pm, then create the meeting if they are
```

Claude runs `availability` before `create_event`, so you don't end up double-booking.

### Search across accounts

If you have multiple grants connected (work and personal email), specify which one:

```
List emails from my work account that mention "quarterly review"
```

Claude uses `get_grant` with your work email address to resolve the correct grant, then runs `list_messages` with a search query filter. You can also ask Claude to search across all connected accounts if you're not sure where a message landed.

## Things to know about Claude Code and Nylas MCP

- **Send confirmations are enforced.** The Nylas MCP server requires a two-step process for sending email: call `confirm_send_message` first, then `send_message` with the confirmation hash. Claude Code handles this automatically, but it means you'll always see a confirmation step before any email is actually sent.

- **Token limits matter.** Large email bodies and long message lists consume Claude's context window. If you're working with high-volume mailboxes, use filters (date range, folder, search query) to keep responses focused. You can also set `MAX_MCP_OUTPUT_TOKENS` to increase the limit if you're hitting truncation.

- **The 90-second timeout applies.** The Nylas MCP server enforces a 90-second timeout on all requests. This is the same limit as the Nylas REST API. For most operations this is plenty, but if you're querying a large date range of events, narrow the window.

- **Grant discovery happens per request.** Unlike the OpenClaw plugin, the MCP server doesn't auto-discover grants at startup. You (or Claude) need to provide an email address, and the server resolves it to a grant ID using `get_grant`. This is more explicit but means Claude needs to know which account to query.

- **Be careful with `--scope project`.** This flag writes your resolved API key into `.mcp.json` at the project root. If you commit that file, you leak the key. Either add `.mcp.json` to `.gitignore` or have each developer run the setup command locally with their own key using the default `local` scope.

- **EU region requires a different URL.** If your Nylas application is in the EU region, use `https://mcp.eu.nylas.com` instead of the US endpoint. The tools and behavior are identical.

## Available tools


The Nylas MCP server exposes these tools to your AI agent:

| Tool | Description |
|---|---|
| `availability` | Find available meeting times across one or more Nylas grants |
| `confirm_send_draft` | Generate the confirmation hash required before calling `send_draft` |
| `confirm_send_message` | Generate the confirmation hash required before calling `send_message` |
| `create_draft` | Create a draft email using only the fields the user provided |
| `create_event` | Create a calendar event |
| `current_time` | Get the current epoch time and ISO 8601 date for a timezone |
| `datetime_to_epoch` | Convert a date, time, and timezone to a Unix timestamp |
| `delete_draft` | Delete a draft email |
| `delete_event` | Delete a calendar event |
| `epoch_to_datetime` | Convert Unix timestamps to human-readable date and time values |
| `get_contact` | Get a single contact by ID |
| `get_event` | Get a single event by ID |
| `get_folder_by_id` | Get folder or label details by ID |
| `get_grant` | Look up a grant by email address |
| `get_message` | Get a single email message by ID, including full body content |
| `get_notetaker` | Get details for one grant-scoped Notetaker bot |
| `get_notetaker_media` | Get fresh media links for one grant-scoped Notetaker bot |
| `get_search_syntax` | Get provider-specific native search syntax for messages and threads |
| `get_standalone_notetaker` | Get details for one standalone Notetaker bot |
| `get_standalone_notetaker_media` | Get fresh media links for one standalone Notetaker bot |
| `list_calendars` | List all calendars for a connected account |
| `list_contacts` | List contacts, with optional filters for email, phone number, source, or group |
| `list_events` | List events in a calendar |
| `list_folders` | List email folders or labels |
| `list_messages` | List and search email messages |
| `list_notetakers` | List grant-scoped Notetaker bots |
| `list_standalone_notetakers` | List standalone Notetaker bots for the application |
| `list_threads` | List and search email threads |
| `schedule_notetaker` | Schedule a grant-scoped Notetaker bot for a future meeting |
| `schedule_standalone_notetaker` | Schedule a standalone Notetaker bot for a future meeting |
| `send_draft` | Send a previously created draft |
| `send_message` | Send an email directly |
| `send_notetaker` | Send a grant-scoped Notetaker bot to an active meeting |
| `send_standalone_notetaker` | Send a standalone Notetaker bot to an active meeting |
| `update_draft` | Update an existing draft |
| `update_event` | Update an existing event |

The `confirm_send_message` and `confirm_send_draft` tools are safety gates that generate a confirmation hash before sending. Your AI agent must call the confirmation tool first, then pass the hash to the send tool. This prevents accidental sends from prompt injection or misinterpreted instructions. The `delete_draft` and `delete_event` tools are irreversible, so confirm with the user before calling them.

For full tool documentation, see the [Nylas MCP reference](/docs/dev-guide/mcp/).


## What's next

- [Nylas MCP reference](/docs/dev-guide/mcp/) for full MCP server documentation, client setup for other tools, and example conversations
- [Email API reference](/docs/api/v3/ecc/#tag--Messages) for endpoint documentation for messages
- [Calendar API reference](/docs/api/v3/ecc/#tag--Events) for endpoint documentation for events
- [Authentication overview](/docs/v3/auth/) to learn how grants and OAuth work
- [Webhooks](/docs/v3/notifications/) for real-time notifications when email or calendar data changes
- [Use Nylas MCP with Codex CLI](/docs/cookbook/ai/mcp/codex-cli/) for the same setup with OpenAI's Codex CLI
- [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp) for the full guide to MCP in Claude Code
- [Build an email agent with Nylas CLI](https://cli.nylas.com/guides/build-email-agent-cli) for a step-by-step CLI walkthrough of building AI email agents
- [Audit AI agent activity](https://cli.nylas.com/guides/audit-ai-agent-activity) to monitor and log what your MCP-connected agents do with email and calendar data