<!-- mcp-name: io.github.cphoskins/nimble-crm-mcp -->

# nimble-crm-mcp

MCP server for the [Nimble CRM](https://www.nimble.com/) API — manage contacts, deals, notes, tasks, and tags from Claude Code or any MCP client.

## Installation

```bash
pip install nimble-crm-mcp
```

Or install from source:

```bash
git clone https://github.com/cphoskins/nimble-crm-mcp.git
cd nimble-crm-mcp
pip install -e .
```

## Configuration

### Get your Nimble API Key

1. Log in to [Nimble](https://app.nimble.com/)
2. Go to **Settings** > **API Tokens** (or visit the [API Access](https://support.nimble.com/en/articles/502755-nimble-api-access) guide)
3. Generate an API key

### Claude Code

Add to your Claude Code MCP settings (`~/.claude/settings.json` or project `.claude/settings.json`):

```json
{
  "mcpServers": {
    "nimble-crm": {
      "command": "nimble-crm-mcp",
      "env": {
        "NIMBLE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Generic MCP Client

```json
{
  "mcpServers": {
    "nimble-crm": {
      "command": "python",
      "args": ["-m", "nimble_crm_mcp.server"],
      "env": {
        "NIMBLE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

## Available Tools

### Contacts
- **list_contacts** — List contacts with optional keyword search and record type filter
- **search_contacts** — Advanced search with field-level operators (is, contains, range, etc.)
- **get_contact** — Get a single contact by ID with all fields and tags
- **create_contact** — Create a person or company contact with name, email, phone, tags
- **update_contact** — Update contact fields (merge or replace mode)
- **delete_contacts** — Delete one or more contacts by ID

### Notes
- **list_notes** — List notes for a specific contact
- **get_note** — Get a single note by ID
- **create_note** — Create a note attached to one or more contacts
- **update_note** — Update an existing note
- **delete_note** — Delete a note

### Tags
- **replace_tags** — Replace all tags on a contact (full replace, not additive)

### Tasks
- **create_task** — Create a task with subject, notes, due date, and related contacts

### Deals
- **list_deals** — List all deals with pagination
- **create_deal** — Create a deal with name, amount, stage, probability, etc.
- **update_deal** — Update deal fields
- **delete_deal** — Delete a deal

### Metadata
- **list_contact_fields** — List all contact field metadata (tabs, groups, fields, types)

### Account
- **get_myself** — Get current authenticated user info

## Development

```bash
# Clone and install
git clone https://github.com/cphoskins/nimble-crm-mcp.git
cd nimble-crm-mcp
pip install -e .

# Run tests (no credentials needed — all mocked)
pytest tests/ -v

# Run the server locally
NIMBLE_API_KEY=your-key nimble-crm-mcp
```

## License

MIT