close-crm-cli

Full-featured CLI and MCP server for the Close CRM platform. Every API endpoint available as a terminal command and as an MCP tool for AI agents.

Features

• 160+ commands across 30 resource groups — full Close API coverage
• MCP server built-in — run close mcp to expose all commands as Claude/Cursor tools
• JSON output by default — pipe to jq, script freely, or feed directly to AI agents
• Authentication via env var, flag, or stored config (close login)
• HTTP Basic Auth — Close's native auth method, handled automatically
• Pagination — offset-based _limit/_skip pagination with has_more
• Retry + rate limit handling — automatic exponential backoff on 429/5xx

Installation

npm install -g close-crm-cli

Or use without installing:

npx close-crm-cli leads list

Authentication

Get your API key from https://app.close.com/settings/api

# Option 1: Environment variable (recommended)
export CLOSE_API_KEY="your-api-key"

# Option 2: Interactive login (stores in ~/.close/config.json)
close login

# Option 3: Per-command flag
close leads list --api-key "your-api-key"

Quick Start

# Get your user profile
close users me

# List leads
close leads list

# Create a lead
close leads create --name "Acme Corp" --url "https://acme.com"

# Create a contact on a lead
close contacts create --lead-id lead_abc123 --name "Jane Doe" \
  --emails '[{"email":"[email protected]","type":"office"}]'

# Log a call
close calls create --lead-id lead_abc123 --direction outbound --duration 900 \
  --note "Discussed Q2 priorities"

# Create a follow-up task
close tasks create --lead-id lead_abc123 --text "Send proposal" \
  --type email --due-date "2025-04-07T09:00:00"

# Move opportunity to next stage
close opportunities update oppo_abc123 --status-id "stat_demo_scheduled"

Output Options

# Default: compact JSON (machine-readable)
close leads list

# Pretty-printed JSON
close leads list --pretty

# Select specific fields
close leads list --fields id,display_name,status_label

# Suppress output (exit codes only: 0=success, 1=error)
close leads list --quiet

Command Groups

| Group | Commands | Description | |-------|----------|-------------| | leads | list, get, create, update, delete, merge, search | CRM leads | | contacts | list, get, create, update, delete | Contacts within leads | | opportunities | list, get, create, update, delete | Pipeline opportunities | | tasks | list, get, create, update, delete, bulk-update | Tasks & follow-ups | | activities | list | Unified activity stream | | calls | list, get, create, update, delete | Call logs | | notes | list, get, create, update, delete | Notes | | emails | list, get, create, update, delete | Email activities | | sms | list, get, create, delete | SMS activities | | meetings | list, get, update, delete | Meetings | | users | me, list, get, availability | Users | | pipelines | list, get, create, update, delete | Sales pipelines | | lead-statuses | list, get, create, update, delete | Lead status labels | | opportunity-statuses | list, get, create, update, delete | Pipeline stages | | custom-fields | list/get/create/update/delete-{lead|contact|opportunity|activity|shared} | Custom fields | | webhooks | list, get, create, update, delete | Webhook subscriptions | | sequences | list, get, create, update, delete, subscribe, list-subscriptions | Outreach sequences | | email-templates | list, get, create, update, delete, render | Email templates | | sms-templates | list, get, create, update, delete | SMS templates | | smart-views | list, get, create, update, delete | Saved views | | reports | activity-metrics, activity-report, funnel | Analytics | | phone-numbers | list, get, update, delete | Phone numbers | | connected-accounts | list, get | Connected email accounts | | organizations | get, update | Organization settings | | groups | list, get, create, update, delete | User groups | | roles | list, get | User roles | | exports | list, get, create-lead, create-opportunity | Data exports | | unsubscribe | list, add, delete | Email unsubscribe list |

MCP Server

Expose all commands as tools for Claude, Cursor, Windsurf, or any MCP-compatible AI:

close mcp

Claude Desktop / Cursor Configuration

Add to your MCP config (~/.claude/config.json or Cursor settings):

{
  "mcpServers": {
    "close": {
      "command": "npx",
      "args": ["close-crm-cli", "mcp"],
      "env": {
        "CLOSE_API_KEY": "your-api-key"
      }
    }
  }
}

Or with a global install:

{
  "mcpServers": {
    "close": {
      "command": "close",
      "args": ["mcp"],
      "env": {
        "CLOSE_API_KEY": "your-api-key"
      }
    }
  }
}

Once configured, Claude can call any Close CRM action directly. Example prompts:

• "List all leads with status Potential"
• "Create a new opportunity for Acme Corp worth $50k"
• "Log a 15-minute outbound call to lead_abc123"
• "Enroll Jane Doe in the Q1 follow-up sequence"
• "Show me this week's activity metrics"

Pagination

# First page
close leads list --limit 50

# Next page
close leads list --limit 50 --skip 50

Custom Fields

# List available custom fields
close custom-fields list-lead

# Set custom fields on create/update
close leads create --name "Acme Corp" --custom '{"cf_budget":"500000","cf_industry":"SaaS"}'
close leads update lead_abc123 --custom '{"cf_stage":"Pilot"}'

Advanced Search

# Simple query string
close leads list --query "Acme"

# Advanced DSL via POST /data/search/
close leads search --query '{
  "type": "and",
  "queries": [
    {"type":"field","field":{"type":"regular","field_name":"status_label"},"negate":false,"condition":{"type":"text","mode":"equals","value":"Potential"}}
  ]
}' --limit 100

Development

git clone https://github.com/bcharleson/close-crm-cli
cd close-crm-cli
npm install

# Run in dev mode
npm run dev -- leads list

# Build
npm run build

# Type check
npm run typecheck

Architecture

The CLI is built on a CommandDefinition pattern — one object per API endpoint that serves as the single source of truth for both the CLI subcommand and the MCP tool:

interface CommandDefinition {
  name: string;          // MCP tool name (e.g. "leads_create")
  group: string;         // CLI group (e.g. "leads")
  subcommand: string;    // CLI subcommand (e.g. "create")
  description: string;   // Used in --help and MCP tool description
  inputSchema: ZodObject; // Shared input validation
  cliMappings: CliMapping; // How fields map to CLI args/options
  endpoint: { method, path }; // HTTP endpoint
  fieldMappings: Record<string, 'path'|'query'|'body'>; // Where fields go
  handler: Function;     // Executes the request
}

See AGENTS.md for the full AI agent integration guide.

License

MIT