# Give your agent contacts access

Source: https://developer.nylas.com/docs/v3/getting-started/agent-contacts/

Your agent needs contacts access to look up people by name or email, enrich context before sending messages, and manage address books on behalf of users. The Nylas CLI gives your agent access to contacts across Gmail, Outlook, Exchange, and iCloud through shell commands that return structured JSON.

## Prerequisites

Make sure the CLI is installed and authenticated. If not, follow the [AI agents quickstart](/docs/v3/getting-started/cli-for-agents/) first.

```bash
nylas auth whoami --json
```

## Search contacts

Find contacts by name or email. This is the most common operation -- look someone up before sending an email or scheduling a meeting.

```bash
nylas contacts search --query "Alice" --json
```

```bash
nylas contacts search --query "alice@example.com" --json
```

## List contacts

List all contacts for the connected user.

```bash
nylas contacts list --limit 10 --json
```

## View contact details

Get the full details for a specific contact -- emails, phone numbers, company, job title.

```bash
nylas contacts show <CONTACT_ID> --json
```

## Create a contact

Add a new contact to the user's address book.

```bash
nylas contacts create --name "Bob Smith" --email "bob@example.com"
```

## List contact groups

See how contacts are organized (labels in Gmail, folders in Outlook).

```bash
nylas contacts groups list --json
```

### Example: enrich context before sending email

A common agent pattern -- look up the recipient before composing a message:

```bash
# 1. Search for the contact
nylas contacts search --query "alice@example.com" --json

# 2. (Agent uses contact details like company, title, and
#     recent interactions to personalize the email)

# 3. Send a personalized email
nylas email send \
  --to "alice@example.com" \
  --subject "Following up on our conversation" \
  --body "Hi Alice, great talking with you at the conference..." \
  --yes
```

### Using MCP instead

If your agent supports [Model Context Protocol](https://modelcontextprotocol.io/) (Claude Code, Cursor, Windsurf, VS Code, Codex CLI), register the CLI as an MCP server for typed contact tools:

```bash
nylas mcp install --assistant claude-code
```

See the [Nylas MCP server docs](/docs/dev-guide/mcp/) for details.

## What's next

- **[Give your agent email access](/docs/v3/getting-started/agent-email/)** -- read, send, and search email
- **[Give your agent calendar access](/docs/v3/getting-started/agent-calendar/)** -- manage events and check availability
- **[Give your agent call recordings](/docs/v3/getting-started/agent-notetaker/)** -- record meetings and get transcripts
- **[AI agents quickstart](/docs/v3/getting-started/cli-for-agents/)** -- full CLI setup and command reference