How to use Nylas MCP with Claude Code

Copy as MarkdownCurl Markdown

Open in

Claude Code is Anthropic’s AI coding agent for the terminal. By connecting it to the Nylas MCP server, you give Claude direct access to email, calendar, and 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, Outlook, Yahoo, iCloud, Exchange, 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 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.).

New to Nylas? The Getting started guide 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.

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:

CLI

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

add-json

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

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:

CLI

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 [email protected] 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 [email protected] 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 [email protected] 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
list_messages	List and search email messages with filters (folder, date range, search query)
send_message	Send an email (requires confirm_send_message first)
create_draft	Create a draft email for review before sending
update_draft	Update an existing draft
send_draft	Send a previously created draft (requires confirm_send_draft first)
list_threads	List and search email threads
get_folder_by_id	Get folder details by ID
list_calendars	List all calendars for a connected account
list_events	List calendar events with date range and calendar filters
create_event	Create a new calendar event
update_event	Update an existing event
availability	Check free/busy availability for participants
get_grant	Look up a grant by email address
current_time	Get the current time in epoch and ISO 8601 format
epoch_to_datetime	Convert epoch timestamps to human-readable dates

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.

For full tool documentation, see the Nylas MCP reference.

What’s next

• Nylas MCP reference for full MCP server documentation, client setup for other tools, and example conversations
• Email API reference for endpoint documentation for messages
• Calendar API reference for endpoint documentation for events
• Authentication overview to learn how grants and OAuth work
• Webhooks for real-time notifications when email or calendar data changes
• Use Nylas MCP with Codex CLI for the same setup with OpenAI’s Codex CLI
• Claude Code MCP documentation for the full guide to MCP in Claude Code
• Build an email agent with Nylas CLI for a step-by-step CLI walkthrough of building AI email agents
• Audit AI agent activity to monitor and log what your MCP-connected agents do with email and calendar data