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

# Set Up an MCP Contacts Server

An MCP contacts server gives an AI client direct access to the address book without custom code. This guide installs, configures, and verifies the Nylas contacts MCP server for Claude Code, Cursor, Windsurf, VS Code, and Claude Desktop, then walks through the search and read tools the assistant calls.

Written by [Caleb Geene](https://cli.nylas.com/authors/caleb-geene) Director, Site Reliability Engineering

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

Updated June 9, 2026

> **TL;DR:** Run [`nylas mcp install --assistant claude-code`](https://cli.nylas.com/docs/commands/mcp-install) and your assistant can search and read contacts through the same server that powers the email and calendar tools. One detail about how Google syncs the address book decides whether a brand-new contact is visible — covered in the verify section below.

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 proxy, [`nylas mcp status`](https://cli.nylas.com/docs/commands/mcp-status) for confirming configuration, and [`nylas contacts search`](https://cli.nylas.com/docs/commands/contacts-search) for the lookup logic the server exposes.

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

An MCP contacts server is a local process that exposes address-book operations — list contacts, search by company or email, read a single record — as tools an AI client calls over the [Model Context Protocol](https://modelcontextprotocol.io/). The Nylas CLI ships one built in. Installing it takes three steps and runs in under 60 seconds if Homebrew is already present.

The contact tools ride on the same server entry as the email and calendar tools, so no separate contacts install exists. MCP reached 97 million monthly SDK downloads by March 2026, and the public registry listed over 9,400 servers. For the mailbox counterpart, see the [MCP email server guide](https://cli.nylas.com/guides/mcp-email-server-setup).

The commands below add the CLI and authenticate the account. The OAuth flow opens a browser, stores the grant in `~/.config/nylas/`, and refreshes tokens automatically every 3,600 seconds. For shell-script, PowerShell, and Go install methods, see the [getting started guide](https://cli.nylas.com/guides/getting-started).

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

# Authenticate your account
nylas auth login

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

Once authenticated, register the server with [`nylas mcp install`](https://cli.nylas.com/docs/commands/mcp-install). The command detects which of the 5 supported assistants are installed, writes the correct JSON config, and for Claude Code adds the tool-permission entries so prompts are pre-approved. Run it once per machine.

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

# Or target a specific assistant
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 assistants at once
nylas mcp install --all
```

## How do I configure the contacts MCP server per tool?

The `nylas mcp install` command writes the config for you, but knowing what it writes helps with debugging. Every one of the 5 supported assistants uses the same JSON block: it points at the `nylas` binary and passes `mcp serve` as the startup argument. The server speaks JSON-RPC over STDIO, which all of them expect.

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

Place that block in the config file for your assistant. The `mcp serve` proxy injects the grant ID automatically, so the agent never needs to know which account it is reading. The table below lists where each of the 5 tools reads its config and whether the scope is project-local or global.

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

## What contact tools does the MCP server expose?

The Nylas contacts MCP server exposes a read surface over the address book: list contacts and look up individual records by email, company, or phone. These tools map to the same logic as the `nylas contacts` command family, which auto-paginates past 200 records. Each call returns structured fields the agent can quote directly, such as name, email, and company.

| Capability | What it does | CLI equivalent |
| --- | --- | --- |
| List contacts | Return address-book entries for the grant | `nylas contacts list` |
| Search contacts | Filter by company, email, phone, or group | `nylas contacts search` |
| Read a contact | Show full detail for one record | `nylas contacts show` |

The search capability is the one assistants reach for first, because finding a person precedes reading their detail. You can run the same query from the terminal to confirm the data the agent will see. The command below filters the address book by company and returns matching contacts with email addresses in under 1 second.

```bash
# Search the address book by company -- the data the search tool returns
nylas contacts search --company "Acme" --has-email --json

# Filter the full list by a single email address
nylas contacts list --email "alice@example.com" --json
```

When the assistant picks a record, it reads the full contact, which maps to the show command below. The `nylas contacts show` command takes a provider-native contact ID and prints every stored field. Pass `--json` to get a machine-readable payload the agent can parse without scraping a table.

```bash
# Read one contact in full by its provider-native ID
nylas contacts show <contact-id> --json
```

## How do I verify the contacts MCP server works?

The [`nylas mcp status`](https://cli.nylas.com/docs/commands/mcp-status) command checks all 5 supported assistants in one pass and reports which have the Nylas server configured. It reads each config file, confirms the `nylas` entry exists, and flags installed tools that are not yet connected. Run it right after install to catch a missing entry.

```bash
nylas mcp status
```

For an end-to-end test, open your assistant and ask it to find a known colleague by name or company. That request routes through the contact search tool and confirms the full chain: STDIO transport, grant injection, the API call, and field parsing. If the assistant returns the right email address, reads work end to end.

Here is the TL;DR detail. Contact sync is provider-dependent, so a contact created seconds ago may not appear yet. Google syncs the address book on a poll cycle of roughly 5 minutes, while Microsoft updates in near real time through Graph. If the agent cannot find a brand-new contact, wait one poll cycle and retry before assuming the server is broken.

### Common errors and fixes

Roughly 90% of reported contacts MCP issues trace to 3 causes: the CLI is not authenticated, the assistant cached an old config, or a recently added contact has not synced yet. Each fix takes under 60 seconds, except the sync delay, which clears within one Google poll cycle.

| Error | Cause | Fix |
| --- | --- | --- |
| `No authenticated grants found` | CLI isn't authenticated | Run `nylas auth login`, then restart the assistant |
| New contact missing | Google sync lag (~5 minutes) | Wait one poll cycle, then check `nylas contacts sync` |
| Tools not appearing | Assistant needs a restart after config change | Restart the assistant so it respawns the `mcp serve` process |

## Why use MCP instead of calling each contacts API directly?

MCP and direct contacts API calls solve different problems. MCP gives an AI client a standard way to discover and call address-book tools with zero glue code, while direct API calls are faster and cheaper per operation for bulk export. The best agents use both: MCP for interactive lookups during a conversation, direct API for batch sync. The protocol removes provider-specific quirks the agent would otherwise handle.

Contacts APIs diverge sharply between providers. Google's [People API connections.list](https://developers.google.com/people/api/rest/v1/people.connections/list) endpoint uses a `personFields` mask and resource names, while Microsoft Graph's [list contacts](https://learn.microsoft.com/en-us/graph/api/user-list-contacts) endpoint returns OData entities with different field names. The [vCard RFC 6350](https://datatracker.ietf.org/doc/html/rfc6350) standardizes the contact model, but each provider implements it differently. The MCP server normalizes all of this, so the agent calls one search tool regardless of backend, the same way the email server unifies sending.

| Factor | MCP | Direct API |
| --- | --- | --- |
| Setup time | Under 60 seconds (`nylas mcp install`) | 5-15 minutes (API keys, SDK, code) |
| Provider differences | Normalized to one tool schema | Handled per provider in your code |
| Tool discovery | Automatic at startup | Requires documentation or skill files |
| Best for | Interactive contact lookups | High-volume address-book export |

## Next steps

- [Full command reference](https://cli.nylas.com/docs/commands) — every flag, subcommand, and example
- [Set up an MCP email server](https://cli.nylas.com/guides/mcp-email-server-setup) — the mailbox counterpart that shares the same server entry
- [Set up an MCP calendar server](https://cli.nylas.com/guides/mcp-calendar-server-setup) — expose availability and event tools to the same assistant
- [Manage contacts from the terminal](https://cli.nylas.com/guides/manage-contacts-from-terminal) — the full list, search, create, and update reference
- [Email MCP server for AI agents](https://cli.nylas.com/guides/ai-agent-email-mcp) — tools, architecture, and example prompts
- [Build an Agency Swarm email agent](https://cli.nylas.com/guides/agency-swarm-email-agent) — the multi-agent alternative that wraps CLI subprocesses
- [Sync email to SQLite](https://cli.nylas.com/guides/email-to-sqlite) — the batch-export pattern for when MCP lookups are too slow
- [Model Context Protocol specification](https://modelcontextprotocol.io/) — the open protocol standard created and maintained by Anthropic
- [Nylas MCP documentation](https://developer.nylas.com/docs/dev-guide/mcp/) — the upstream server reference
- [vCard RFC 6350](https://datatracker.ietf.org/doc/html/rfc6350) — the contact data model providers implement differently