npm package: @solapi/crm-mcp-server
Description: MCP server for SOLAPI CRM API integration — query customers, manage automations, and more from Claude, Cursor, and other AI assistants
Latest version: 1.0.5

# @solapi/crm-mcp-server

SOLAPI CRM의 고객 데이터를 AI 어시스턴트(Claude, Cursor 등)에서 직접 조회하고 관리할 수 있는 MCP 서버입니다.

## 빠른 시작

### 1. 설치 & 설정 (한 번에)

```bash
npx @solapi/crm-mcp-server setup
```

대화형 설정 도우미가 실행되어:
1. **SOLAPI API Key / Secret** 입력을 안내합니다 ([콘솔에서 발급](https://console.solapi.com))
2. 설치된 **AI 클라이언트를 자동 감지**합니다 (Claude Desktop, Cursor, Claude Code)
3. API 키를 **검증**하고 설정 파일에 저장합니다

> AI 에이전트나 스크립트에서 비대화형으로 설정하려면:
> ```bash
> npx @solapi/crm-mcp-server setup --api-key YOUR_KEY --api-secret YOUR_SECRET
> npx @solapi/crm-mcp-server setup --api-key YOUR_KEY --api-secret YOUR_SECRET --client claude-code
> ```

### 2. 재시작

Claude Desktop 또는 Cursor를 재시작하면 CRM 도구가 활성화됩니다.

<details>
<summary>수동 설치 (패키지 매니저별)</summary>

| Package Manager | 명령어 |
|---|---|
| **npm** | `npm install -g @solapi/crm-mcp-server` |
| **yarn** | `yarn global add @solapi/crm-mcp-server` |
| **pnpm** | `pnpm add -g @solapi/crm-mcp-server` |
| **bun** | `bun add -g @solapi/crm-mcp-server` |

설치 후 `npx @solapi/crm-mcp-server setup`으로 설정하세요.
</details>

---

## 이런 것들을 할 수 있어요

### 고객 데이터 관리

```
💬 "우리 CRM에 어떤 개체들이 있는지 보여줘"
💬 "고객 개체에 어떤 속성(필드)들이 있어?"
💬 "'삼성' 관련 고객 레코드 찾아줘"
💬 "고객 ID rec_abc123의 상세 정보 보여줘"
💬 "새 고객 '홍길동'을 추가해줘. 이메일은 hong@example.com이야"
💬 "김철수 고객의 등급을 VIP로 변경해줘"
💬 "이 고객 레코드 삭제해줘"
```

### 세그먼트 관리

```
💬 "고객 개체에 설정된 세그먼트 목록 보여줘"
💬 "VIP 세그먼트에 속한 고객들 알려줘"
💬 "VIP 세그먼트의 조건이 뭐야?"
💬 "서울 거주이면서 최근 30일 내 구매 3회 이상인 고객을 미리보기해줘"
💬 "위 조건으로 '서울 우수 고객' 세그먼트를 만들어줘"
💬 "이 세그먼트 조건에 '태그에 VIP 포함' 조건도 추가해줘"
```

### 활동 기록 & 관계 분석

```
💬 "김철수 고객의 최근 활동 이력 보여줘"
💬 "이 고객에게 '상담 전화 — 상품 문의' 통화 기록 남겨줘"
💬 "다음 주 화요일 오후 2시에 미팅 일정 잡아줘"
💬 "이 고객에 대한 메모: '계약 갱신 논의 필요' 추가해줘"
💬 "이 고객의 활동 통계 요약해줘"
💬 "이 고객과 연결된 회사, 거래가 있어?"
💬 "우리 CRM에 어떤 관계 타입이 정의되어 있어?"
```

### 대시보드 & 이벤트

```
💬 "메인 대시보드 현황 보여줘"
💬 "이 고객의 이벤트 요약 알려줘"
💬 "우리 팀 멤버 목록 보여줘"
💬 "현재 요금 플랜과 사용량 보여줘"
```

### 자동화 모니터링 & 제어

```
💬 "현재 활성화된 자동화 목록 보여줘"
💬 "'신규 고객 환영 메시지' 자동화의 실행 현황 알려줘"
💬 "이 자동화에서 최근 실패한 실행들 보여줘"
💬 "실패한 실행의 에러 로그 확인해줘"
💬 "이번 달 자동화 실행 횟수와 크레딧 사용량 알려줘"
💬 "이 자동화 일시 정지해줘"
💬 "다시 활성화해줘"
💬 "이 고객들을 '재구매 유도' 자동화에 수동 등록해줘"
```

### 자동화 생성 ✨

```
💬 "고객이 VIP 세그먼트에 들어오면 환영 알림톡을 보내는 자동화 만들어줘"
💬 "신규 가입 후 3일 뒤에 후속 SMS를 보내는 자동화 만들어줘"
💬 "거래 금액이 1000만원 이상으로 변경되면 팀장에게 알려주는 자동화 만들어줘"
💬 "매주 월요일 아침 9시에 미완료 활동 알림 보내는 자동화 만들어줘"
💬 "신규 고객 등록 시 3일 후 미팅 일정을 자동으로 만들어주는 자동화 만들어줘"
```

> 자동화는 DRAFT 상태로 생성됩니다. CRM 대시보드에서 확인 후 활성화하세요.
>
> 메시지 발송 시 **메시지 템플릿은 필수가 아닙니다.** SMS 자유 텍스트, 카카오 알림톡, 이메일 등 채널별로 직접 내용을 설정할 수 있으며, 마스킹된 속성을 사용해야 하는 경우에만 메시지 템플릿이 필요합니다.

### 복합 분석 시나리오

```
💬 "VIP 고객 중 최근 3개월 동안 연락이 없었던 사람들을 찾아서 정리해줘"
💬 "이번 달 신규 가입 고객 수와 주요 유입 채널을 분석해줘"
💬 "각 영업 담당자별로 관리 중인 거래 건수와 총 금액을 정리해줘"
💬 "실패율이 높은 자동화를 찾아서 원인을 분석해줘"
💬 "VIP 고객 중 '재구매 유도' 자동화에 아직 등록 안 된 사람들을 찾아서 등록해줘"
💬 "현재 플랜 사용량 확인하고, 한도에 가까운 항목 알려줘"
```

---

## 지원 노드 타입

자동화 워크플로우에서 사용할 수 있는 노드 타입입니다. `crm_get_automation_node_types`로 상세 config를 확인할 수 있습니다.

| 카테고리 | 노드 타입 | 설명 |
|---------|----------|------|
| **트리거** | `RECORD_CREATED` | 레코드 생성 시 |
| | `RECORD_UPDATED` | 레코드 수정 시 (특정 필드 감시 가능) |
| | `SEGMENT_ENTERED` | 세그먼트 진입 시 |
| | `SCHEDULE` | Cron 스케줄 |
| | `MANUAL` | 수동 트리거 |
| | `WEBHOOK` | 외부 웹훅 수신 |
| **액션** | `SEND_MESSAGE` | SMS / 카카오 알림톡 / 이메일 발송 |
| | `UPDATE_FIELD` | 레코드 필드 값 수정 |
| | `CREATE_RECORD` | 새 레코드 생성 |
| | `CREATE_ACTIVITY` | 활동(전화/미팅/태스크/노트) 생성 |
| | `HTTP_REQUEST` | 외부 HTTP 요청 |
| | `NOTIFICATION` | 팀 멤버 내부 알림 |
| | `DELAY` | 지정 시간 대기 |
| | `ADD_TAG` | 태그 추가 |
| **조건** | `IF_ELSE` | 조건 분기 (참/거짓) |
| | `SPLIT` | 다중 분기 |
| **제어** | `WAIT` | 시간 대기 |
| | `WAIT_UNTIL` | 조건 충족까지 대기 (최대 90일) |
| | `ROUTE` | 병렬 실행 |
| | `LOOP` | 반복 실행 (1~100회) |
| | `GOTO` | 특정 노드로 이동 |
| | `END` | 워크플로우 종료 |

---

## 사용 가능한 도구 (48개)

### 개체 & 속성
| 도구 | 설명 |
|------|------|
| `crm_list_entities` | 개체 목록 조회 (고객, 회사, 거래 등) |
| `crm_get_entity` | 개체 상세 조회 |
| `crm_list_properties` | 개체의 속성(필드) 목록 조회 |
| `crm_create_entity` | 개체 생성 |
| `crm_update_entity` | 개체 수정 |
| `crm_create_property` | 속성(필드) 생성 |
| `crm_update_property` | 속성(필드) 수정 |

### 레코드
| 도구 | 설명 |
|------|------|
| `crm_list_records` | 레코드 목록 조회 (검색, 필터, 페이지네이션) |
| `crm_get_record` | 레코드 상세 조회 |
| `crm_create_record` | 레코드 생성 (고객, 회사 등 추가) |
| `crm_update_record` | 레코드 수정 (이름, 필드, 태그, 담당자) |
| `crm_delete_record` | 레코드 삭제 (휴지통으로 이동) |

### 활동
| 도구 | 설명 |
|------|------|
| `crm_list_activities` | 활동 목록 조회 (통화, 미팅, 메모 등) |
| `crm_get_activity_stats` | 레코드별 활동 통계 |
| `crm_create_activity` | 활동 기록 생성 (통화, 미팅, 노트, 태스크 등) |

### 세그먼트
| 도구 | 설명 |
|------|------|
| `crm_list_segments` | 세그먼트 목록 조회 |
| `crm_get_segment` | 세그먼트 상세 조회 (조건 포함) |
| `crm_get_segment_records` | 세그먼트 소속 레코드 조회 |
| `crm_preview_segment` | 조건 미리보기 (저장 없이 매칭 확인) |
| `crm_create_segment` | 세그먼트 생성 (복합 조건 지원) |
| `crm_update_segment` | 세그먼트 수정 |
| `crm_delete_segment` | 세그먼트 삭제 |

### 관계
| 도구 | 설명 |
|------|------|
| `crm_list_record_relationships` | 레코드의 관계 목록 조회 |
| `crm_list_relationship_types` | 관계 타입 정의 조회 |
| `crm_create_relationship` | 레코드 간 관계 생성 |
| `crm_update_relationship` | 관계 수정 |
| `crm_create_relationship_type` | 관계 타입 정의 생성 |
| `crm_update_relationship_type` | 관계 타입 정의 수정 |

### 대시보드
| 도구 | 설명 |
|------|------|
| `crm_list_dashboards` | 대시보드 목록 조회 |
| `crm_get_dashboard_data` | 대시보드 위젯 데이터 조회 |

### 이벤트
| 도구 | 설명 |
|------|------|
| `crm_get_event_summaries` | 이벤트 요약 통계 조회 |

### 멤버
| 도구 | 설명 |
|------|------|
| `crm_list_members` | 워크스페이스 멤버 목록 |
| `crm_get_me` | 내 멤버 정보 |

### 플랜
| 도구 | 설명 |
|------|------|
| `crm_get_plan_usage` | 현재 플랜 및 사용량 조회 |

### 자동화
| 도구 | 설명 |
|------|------|
| `crm_list_automations` | 자동화 목록 조회 |
| `crm_get_automation` | 자동화 상세 (워크플로우 포함) |
| `crm_get_automation_stats` | 자동화 노드별 실행 통계 |
| `crm_list_automation_executions` | 자동화 실행 이력 |
| `crm_get_automation_logs` | 자동화 실행 로그 |
| `crm_get_automation_metering` | 자동화 크레딧 사용량 |
| `crm_activate_automation` | 자동화 활성화 |
| `crm_pause_automation` | 자동화 일시 정지 |
| `crm_enroll_automation` | 레코드 수동 등록 |
| `crm_list_message_templates` | 메시지 템플릿 목록 (마스킹 속성 사용 시 필요) |
| `crm_get_automation_node_types` | 자동화 노드 타입 레퍼런스 |
| `crm_create_automation` | 자동화 워크플로우 생성 (DRAFT) |

---

## 수동 설정

> `npx @solapi/crm-mcp-server setup`으로 자동 설정하는 것을 권장합니다.

<details>
<summary>Claude Desktop</summary>

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "solapi-crm": {
      "command": "npx",
      "args": ["-y", "@solapi/crm-mcp-server"],
      "env": {
        "SOLAPI_API_KEY": "your-api-key",
        "SOLAPI_API_SECRET": "your-api-secret"
      }
    }
  }
}
```
</details>

<details>
<summary>Cursor</summary>

`~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "solapi-crm": {
      "command": "npx",
      "args": ["-y", "@solapi/crm-mcp-server"],
      "env": {
        "SOLAPI_API_KEY": "your-api-key",
        "SOLAPI_API_SECRET": "your-api-secret"
      }
    }
  }
}
```
</details>

<details>
<summary>Claude Code</summary>

```bash
claude mcp add solapi-crm \
  --env SOLAPI_API_KEY=your-key \
  --env SOLAPI_API_SECRET=your-secret \
  -- npx -y @solapi/crm-mcp-server
```

또는 비대화형:

```bash
npx @solapi/crm-mcp-server setup --api-key YOUR_KEY --api-secret YOUR_SECRET --client claude-code
```
</details>

---

## `@solapi/mcp-server`와의 차이점

| | `@solapi/mcp-server` | `@solapi/crm-mcp-server` |
|--|--|--|
| **목적** | SOLAPI 개발 문서 검색 & SDK 예제 조회 | CRM 데이터 실시간 조회 & 관리 |
| **데이터** | 정적 (빌드 시 번들된 예제/문서) | 동적 (라이브 CRM API 호출) |
| **인증** | 불필요 | SOLAPI API Key + Secret 필수 |
| **대상** | SOLAPI 연동을 개발하는 개발자 | CRM을 사용하는 비즈니스 사용자/운영자 |
| **예시** | "카카오 알림톡 발송 코드 보여줘" | "지난주 가입한 VIP 고객 목록 찾아줘" |

두 서버는 독립적이며 **동시 설치하여 병행 사용** 가능합니다.

---

## 환경변수

| 변수 | 필수 | 설명 |
|------|------|------|
| `SOLAPI_API_KEY` | ✅ | SOLAPI 계정 API Key |
| `SOLAPI_API_SECRET` | ✅ | SOLAPI 계정 API Secret |
| `SOLAPI_BASE_URL` | ❌ | API Base URL (기본: `https://api.solapi.com`) |

---

## SOLAPI CRM 더 알아보기

고객 관리, 자동화, 세그먼트, 대시보드까지 — SOLAPI CRM으로 비즈니스를 성장시키세요.

👉 [solapi.com/crm](https://solapi.com/crm)

---

## 라이선스

MIT