# Close CRM MCP Server

A comprehensive Model Context Protocol (MCP) server for Close CRM, providing AI assistants with complete access to sales pipeline management, lead tracking, and customer relationship workflows. This server delivers 70 tools across sales activities, contact management, and pipeline automation.

## Features

- **Lead Management**: Create, search, update, and manage leads with custom fields and status tracking
- **Contact Operations**: Full CRUD operations for contacts with email, phone, and social profile management
- **Opportunity Pipeline**: Track deals through your sales pipeline with custom stages and values
- **Activity Tracking**: Log calls, emails, meetings, and notes with automatic activity timelines
- **Task Management**: Create and assign tasks with due dates, reminders, and priority levels
- **Custom Fields**: Leverage custom fields on leads, contacts, and opportunities for tailored workflows
- **Smart Views**: Access saved filters and custom views for quick data access
- **Sequences**: Manage email sequences and cadences for automated outreach
- **Reporting**: Generate pipeline reports, activity summaries, and team performance metrics
- **Bulk Operations**: Import, export, and update records in bulk
- **User & Team Management**: Manage team members, roles, and permissions
- **Advanced Search**: Query leads, contacts, and opportunities with complex filters

## Installation

```bash
npm install && npm run build
```

## Environment Variables

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `CLOSE_API_KEY` | Yes | Your Close API key | `api_xxxxxxxxxxxxxxxxxxxxxxxx` |

## Getting Your Access Token

1. **Log in to Close**: Go to [app.close.com](https://app.close.com)
2. **Navigate to Settings**: Click the gear icon ⚙️ in the bottom left → **Settings**
3. **API Keys Section**:
   - In the left sidebar, click **Developer** → **API Keys**
   - Or go directly to: `https://app.close.com/settings/developer/api-keys/`
4. **Create API Key**:
   - Click **Create new API key**
   - Enter a name (e.g., "MCP Server Integration")
   - Select access level (usually "Full Access" for MCP integration)
   - Click **Create API Key**
5. **Copy Your Key**: The API key will be displayed once — copy it immediately
6. **Set Environment Variable**:
   ```bash
   export CLOSE_API_KEY="api_xxxxxxxxxxxxxxxxxxxxxxxx"
   ```

**Security Note**: API keys inherit the permissions of the user who created them. Use service accounts or restricted users for production integrations. Never commit API keys to version control.

## Required API Scopes

Close API keys can have different access levels:

**Full Access** (recommended for MCP):
- **Leads**: Read, create, update, delete leads
- **Contacts**: Read, create, update, delete contacts  
- **Opportunities**: Read, create, update, close deals
- **Activities**: Log and read calls, emails, meetings, notes
- **Tasks**: Create and manage tasks
- **Custom Fields**: Read and write custom field values
- **Users**: Read user and team information
- **Smart Views**: Access saved searches and filters
- **Sequences**: Manage email sequences
- **Reporting**: Generate reports and analytics
- **Bulk Operations**: Import/export data

**Read-Only**: Limited to viewing data (not recommended for full MCP functionality)

**Custom**: Select specific permissions per resource type

## Usage

### stdio Mode (Default)

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "close": {
      "command": "node",
      "args": [
        "/path/to/mcpengine-repo/servers/close/dist/index.js"
      ],
      "env": {
        "CLOSE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### HTTP Mode

The server can also run as an HTTP endpoint:

```bash
export CLOSE_API_KEY="your_api_key_here"
npm start -- --http --port 3000
```

Then configure your MCP client to connect to `http://localhost:3000`.

## Coverage Manifest

```
Total API endpoints: ~120 (Close API v1)
Tools implemented: 70
Intentionally skipped: ~30 (webhooks, integrations, SMS, custom email templates)
Not yet covered: ~20 (graph/timeline endpoints, merge operations, import status)
Coverage: 70/120 = 58%
```

**Coverage Notes**:
- ✅ **Complete**: Leads (10 tools), Contacts (9 tools), Opportunities (9 tools), Activities (12 tools), Tasks (6 tools), Custom Fields (6 tools), Users (5 tools), Smart Views (4 tools), Sequences (5 tools), Reporting (4 tools)
- ⏭️ **Skipped**: Webhooks (use Zapier/n8n), SMS activities, integration-specific endpoints, Zoom meeting creation
- 🚧 **Planned**: Lead/contact merge, bulk import status tracking, export jobs, connected accounts

## Example Use Cases

- "Create a new lead for Acme Corp with contact details for their CEO"
- "Show me all leads in the 'Qualified' status assigned to Sarah"
- "Log a call with John Smith about pricing discussion"
- "Create a follow-up task for tomorrow to send proposal to lead #12345"
- "Update the opportunity value to $50k and move to 'Negotiation' stage"
- "Search for all contacts with '@gmail.com' emails"
- "Get pipeline report for this month showing all won deals"
- "Add a lead to the 'New Customer Outreach' sequence"

## Architecture

The server uses a clean, modular architecture:
- **Client**: `CloseClient` with Basic Auth (API key + colon encoding)
- **Tools**: 12 tool modules with 70 total tools
- **Auth**: HTTP Basic Authentication (`api_key:` base64-encoded)
- **Pagination**: Automatic cursor-based pagination for list operations
- **Rate Limits**: Respects Close API rate limits (typically 600 req/min)

## Links

- [Close API Documentation](https://developer.close.com/)
- [Close API Reference](https://developer.close.com/resources/api-reference/)
- [Rate Limits](https://developer.close.com/resources/rate-limits/)
- [Custom Fields Guide](https://help.close.com/article/custom-fields/)
- [Close Help Center](https://help.close.com/)