# Centrex MCP Server

MCP (Model Context Protocol) server for the [Centrex Software](https://centrexsoftware.com) CRM & LOS API v1. Gives Claude direct access to contacts, advances, documents, alerts, users, teams, and lender submissions.

## Quick Install

### Option A — Terminal (Claude Code)

```bash
claude mcp add centrex \
  --command node \
  --args "/path/to/centrex-mcp-server/dist/index.js" \
  -e CENTREX_ACCESS_TOKEN=your_token_here
```

### Option B — Manual JSON config

Add to `~/.claude.json` (global) or `.claude.json` in your project:

```json
{
  "mcpServers": {
    "centrex": {
      "command": "node",
      "args": ["/path/to/centrex-mcp-server/dist/index.js"],
      "env": {
        "CENTREX_ACCESS_TOKEN": "your_access_token_here",
        "CENTREX_ACCOUNT_ID": "optional_account_id",
        "CENTREX_ALLOW_DESTRUCTIVE_OPERATIONS": "false"
      }
    }
  }
}
```

### Option C — Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "centrex": {
      "command": "node",
      "args": ["C:/path/to/centrex-mcp-server/dist/index.js"],
      "env": {
        "CENTREX_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}
```

---

## Installation & Build

```bash
git clone https://github.com/AllianceGS-Development/centrex-mcp-server.git
cd centrex-mcp-server
npm install
npm run build       # compiles TypeScript → dist/
```

Copy `.env.example` to `.env` and fill in your credentials, then point the config to `dist/index.js`.

---

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `CENTREX_ACCESS_TOKEN` | **Yes** | Bearer token from Centrex → Settings → API |
| `CENTREX_ACCOUNT_ID` | No | Lock to a specific account/org ID |
| `CENTREX_ALLOW_DESTRUCTIVE_OPERATIONS` | No | Set `true` to allow DELETE operations (default `false`) |

Get your API access token from your Centrex account under **Settings → API** or contact `support@centrexsoftware.com`.

---

## Tools Reference

### Contacts

#### `centrex_list_contacts`
Search and list contacts with optional filters.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `search` | string | No | Full-text search query |
| `email` | string | No | Filter by email |
| `phone` | string | No | Filter by phone number |
| `status` | string | No | Filter by contact status |
| `limit` | string | No | Results per page (default 25) |
| `offset` | string | No | Pagination offset |

#### `centrex_get_contact`
Get a single contact by ID.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | **Yes** | Contact ID |

#### `centrex_create_contact`
Create a new contact/lead.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `first_name` | string | **Yes** | First name |
| `last_name` | string | **Yes** | Last name |
| `email` | string | No | Email address |
| `phone` | string | No | Phone number |
| `business_name` | string | No | Business/company name |
| `address` | string | No | Street address |
| `city` | string | No | City |
| `state` | string | No | State (2-letter) |
| `zip` | string | No | ZIP code |
| `status` | string | No | Contact status |
| `assigned_user_id` | string | No | User to assign this contact to |

#### `centrex_update_contact`
Update an existing contact (partial update).

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | **Yes** | Contact ID to update |
| `first_name` | string | No | New first name |
| `last_name` | string | No | New last name |
| `email` | string | No | New email |
| `phone` | string | No | New phone |
| `business_name` | string | No | New business name |
| `status` | string | No | New status |
| `assigned_user_id` | string | No | Reassign to user |

#### `centrex_delete_contact`
Delete a contact. Requires `CENTREX_ALLOW_DESTRUCTIVE_OPERATIONS=true`.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | **Yes** | Contact ID to delete |

---

### Contact Notes

#### `centrex_get_contact_notes`
Get all notes for a contact.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | **Yes** | Contact ID |

#### `centrex_create_contact_note`
Add a note to a contact.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | **Yes** | Contact ID |
| `note` | string | **Yes** | Note text |
| `type` | string | No | Note type/category |

---

### Communication

#### `centrex_send_communication`
Send email or SMS to a contact.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | **Yes** | Contact ID |
| `type` | string | **Yes** | `email` or `sms` |
| `message` | string | **Yes** | Message body |
| `subject` | string | Cond. | Required for email |
| `template_id` | string | No | Template ID to use |

---

### Advances (Loans)

#### `centrex_list_advances`
List loan/advance records.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | No | Filter by contact |
| `status` | string | No | Filter by status |
| `limit` | string | No | Results per page |
| `offset` | string | No | Pagination offset |

#### `centrex_create_advance`
Create a new loan/advance record.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | **Yes** | Contact this advance belongs to |
| `amount` | number | **Yes** | Advance amount |
| `status` | string | No | Status |
| `type` | string | No | Advance type |
| `notes` | string | No | Notes |

---

### Documents

#### `centrex_list_documents`
List documents.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | No | Filter by contact |
| `limit` | string | No | Results per page |
| `offset` | string | No | Pagination offset |

#### `centrex_get_document`
Get document metadata and download URL.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `document_id` | string | **Yes** | Document ID |

---

### Alerts

#### `centrex_list_alerts`
List alerts/reminders.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | No | Filter by contact |
| `status` | string | No | Filter by status |
| `limit` | string | No | Results per page |
| `offset` | string | No | Pagination offset |

#### `centrex_create_alert`
Create an alert/reminder.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | **Yes** | Contact ID |
| `message` | string | **Yes** | Alert message |
| `due_date` | string | No | ISO 8601 due date |
| `assigned_user_id` | string | No | User to assign to |
| `type` | string | No | Alert type |

---

### Users & Teams

#### `centrex_list_users`
List users/agents.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `limit` | string | No | Results per page |
| `offset` | string | No | Pagination offset |

#### `centrex_get_user`
Get a user by ID.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `user_id` | string | **Yes** | User ID |

#### `centrex_list_teams`
List teams.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `limit` | string | No | Results per page |
| `offset` | string | No | Pagination offset |

---

### Lender Submissions

#### `centrex_list_submissions`
List lender submission records.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | string | No | Filter by contact |
| `status` | string | No | Filter by status |
| `limit` | string | No | Results per page |
| `offset` | string | No | Pagination offset |

#### `centrex_get_submission`
Get a specific submission.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `submission_id` | string | **Yes** | Submission ID |

---

### Generic Escape Hatch

#### `centrex_request`
Make a raw authenticated request to any Centrex API endpoint not covered by dedicated tools.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `method` | string | **Yes** | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` |
| `path` | string | **Yes** | API path starting with `/` (e.g. `/contacts/123/forms`) |
| `params` | object | No | Query string parameters |
| `body` | object | No | Request body for POST/PUT/PATCH |

---

## Centrex API Endpoint Reference

| Resource | Method | Endpoint | Description |
|---|---|---|---|
| Contacts | GET | `/contacts` | List/search contacts |
| Contacts | POST | `/contacts` | Create contact |
| Contacts | GET | `/contacts/{id}` | Get contact |
| Contacts | PUT | `/contacts/{id}` | Update contact |
| Contacts | DELETE | `/contacts/{id}` | Delete contact |
| Contact Notes | GET | `/contacts/{id}/notes` | Get notes |
| Contact Notes | POST | `/contacts/{id}/notes` | Add note |
| Communication | POST | `/contacts/{id}/communication` | Send email/SMS |
| Forms | POST | `/contacts/{id}/forms` | Send external form |
| Advances | GET | `/advances` | List advances |
| Advances | POST | `/advances` | Create advance |
| Advances | GET | `/advances/{id}` | Get advance |
| Advances | PUT | `/advances/{id}` | Update advance |
| Documents | GET | `/documents` | List documents |
| Documents | POST | `/documents` | Upload document |
| Documents | GET | `/documents/{id}` | Get document |
| Alerts | GET | `/alerts` | List alerts |
| Alerts | POST | `/alerts` | Create alert |
| Alerts | PUT | `/alerts/{id}` | Update alert |
| Alerts | DELETE | `/alerts/{id}` | Delete alert |
| Users | GET | `/users` | List users |
| Users | POST | `/users` | Create user |
| Users | GET | `/users/{id}` | Get user |
| Users | PUT | `/users/{id}` | Update user |
| Users | DELETE | `/users/{id}` | Delete user |
| Users | GET | `/users/preferences` | User preferences |
| Teams | GET | `/teams` | List teams |
| Teams | POST | `/teams` | Create team |
| Teams | GET | `/teams/{id}` | Get team |
| Teams | PUT | `/teams/{id}` | Update team |
| Teams | DELETE | `/teams/{id}` | Delete team |
| Submissions | GET | `/submissions` | List submissions |
| Submissions | GET | `/submissions/{id}` | Get submission |
| Submissions | GET | `/submissions/{id}/status` | Submission status |
| Credit Reports | GET | `/credit-reports` | Credit report data |
| Webhooks | POST | `/webhooks` | Configure webhooks |

---

## Security

- Bearer token is never logged or exposed in output
- Sensitive fields are redacted from responses
- SSRF protection: only `api.centrexsoftware.com` is reachable
- Destructive operations (DELETE) require explicit opt-in via `CENTREX_ALLOW_DESTRUCTIVE_OPERATIONS=true`

## License

MIT — Alliance Global Solutions 2026