Claude에게 Pipedrive CRM API에 대한 포괄적인 접근 권한을 제공하는 프로덕션 준비 완료된 Model Context Protocol (MCP) 서버입니다. 이 서버는 자연어 대화를 통해 영업 워크플로우, 딜 관리 (deal management), 연락처 정리 및 활동 추적의 원활한 자동화를 가능하게 합니다.

개발 및 유지 관리:

Nubiia— 비즈니스를 위한 AI 자동화 및 통합 (MCP, Holded, Pipedrive 등). 귀사의 기업을 위해 유사한 솔루션이 필요하신가요? ennubiia.es로 문의해 주세요.

29개 카테고리에 걸친 300개 이상의 도구

• 전체 Pipedrive REST API (v1 + v2)의 완전한 커버리지
  고급 속도 제한 (Rate Limiting)
• 초당 10개 요청, 최대 100개 요청까지 버스트 (burst) 용량 지원
  다단계 캐싱 (Multi-Level Caching)
• 자주 액세스하는 데이터에 대해 5-15분 TTL 적용
  재시도 로직 (Retry Logic)
• 실패한 요청에 대해 지수 백오프 (Exponential backoff) 적용 (429, 500, 502, 503, 504)
  포괄적인 오류 처리 (Error Handling)
• 실행 가능한 제안이 포함된 상세한 오류 메시지
  전체 TypeScript 지원
• 전 과정에 걸친 타입 안전 (Type-safe) 스키마 및 인터페이스
  Zod 검증 (Validation)
• 유용한 오류 메시지를 포함한 모든 입력값에 대한 런타임 검증
  MCP 리소스 (Resources)
• 파이프라인 (pipelines), 커스텀 필드 (custom fields) 및 사용자 정보에 대한 읽기 전용 접근
  MCP 프롬프트 (Prompts)
• 일반적인 작업을 위한 5가지 가이드 워크플로우
  성능 지표 (Performance Metrics)
• 요청 지속 시간 및 성공률에 대한 내장 추적 기능
  읽기 전용 모드 (Read-Only Mode)
• 모든 쓰기 작업을 차단하는 선택적 안전 모드
  도구 세트 필터링 (Toolset Filtering)
• 필요에 따라 특정 도구 카테고리를 활성화/비활성화

29개 카테고리에 걸친 307개 도구 — Pipedrive REST API (v1 + v2)의 완전한 커버리지:

카테고리	도구 수	설명
Deals (딜)	43	전체 라이프사이클: CRUD, 단계 (stages), 참여자 (participants), 제품 (products), 파일 (files), 병합 (merge), 전환 (conversions), 할부 (installments) (v2)
Fields (필드)	30	커스텀 필드 탐색 + 딜/사람/조직/제품/프로젝트 필드에 대한 CRUD, 그리고 리드(lead) 및 노트(note) 필드
Persons (사람)	23	커스텀 필드, 활동 (activities), 딜, 파일 및 팔로워 (followers)를 포함한 연락처 관리
Organizations (조직)	21	사람, 딜 및 활동과의 관계를 포함한 회사 관리
Projects (프로젝트)	16	프로젝트, 보드 (boards), 단계 (phases), 그룹 (groups), 작업 (tasks) 및 계획 (plan) 관리
Pipelines (파이프라인)	15	파이프라인 관리, 단계 (stages), 전환 및 이동 통계
Leads (리드)	15	리드 CRUD, 라벨 (labels), 소스 (sources), 검색 및 리드↔딜 전환
Roles (역할)	14	역할, 할당 (assignments), 설정 (settings) 및 파이프라인 가시성
Products (제품)	13	제품 카탈로그, 딜/사람 첨부 파일, 파일 및 팔로워 (followers)
Users (사용자)	12	사용자, 권한 (permissions), 팔로워 (followers) 및 역할 할당
Notes (노트)	9	딜, 사람 및 조직에 대한 노트와 댓글 (comments)
Activities (활동)	9	마감일 (due dates) 및 완료를 포함한 작업 (task), 통화 (call), 회의 (meeting) 일정 예약
System (시스템)	9	상태 (health), 지표 (metrics), 통화 (currencies), 사용자 설정, 최근 항목 및 캐시 (cache)
Teams (팀)	8	팀 관리 및 멤버십
Files (파일)	7	파일 업로드, 다운로드, 관리 및 원격 파일 연결
Filters (필터)	7	필터 CRUD 및 헬퍼 메타데이터 (helper metadata)
Search (검색)	6	범용 및 엔티티별 (entity-specific) 검색
Mailbox (메일함)	6	메일 스레드 (threads) 및 메시지
Stages (단계)	5	파이프라인 단계 CRUD (v2)
Tasks (작업)	5	프로젝트 작업 관리
Goals (목표)	5	목표 CRUD 및 결과
Call logs (통화 로그)	5	통화 로그 CRUD 및 오디오 첨부 파일
Activity types (활동 유형)	5	활동 유형 관리
Org relationships (조직 관계)	5	조직 간 관계
Channels (채널)	4	메시징 채널 통합
Webhooks (웹훅)	3	웹훅 CRUD
Permission sets (권한 세트)	3	권한 세트 조사 및 할당
Project templates (프로젝트 템플릿)	2	프로젝트 템플릿 탐색
Meetings (회의)	2	화상 통화 제공업체 연결

npm install -g @nubiia/mcp-pipedrive

npx -y @nubiia/mcp-pipedrive

• Settings > API에서 Pipedrive API 토큰을 가져오세요
• Claude Desktop이 설치되어 있어야 합니다

~/Library/Application Support/Claude/claude_desktop_config.json 파일을 편집하세요

:

{
"mcpServers": {
"pipedrive": {
...

%APPDATA%\Claude\claude_desktop_config.json 파일을 편집하세요

:

{
"mcpServers": {
"pipedrive": {
...

변수 (Variable)	필수 여부	기본값	설명
PIPEDRIVE_API_TOKEN	예	-	귀하의 Pipedrive API 토큰
PIPEDRIVE_READ_ONLY	아니요	false	읽기 전용 모드 활성화 (모든 쓰기 작업 차단)
PIPEDRIVE_TOOLSETS	아니요	deals,persons,organizations,activities	활성화할 도구 카테고리 목록 (쉼표로 구분)
LOG_LEVEL	아니요	info	로깅 레벨 (debug, info, warn, error)

탐색적 사용이나 실수로 인한 수정을 방지하고 싶을 때 완벽합니다:

{
"mcpServers": {
"pipedrive": {
...

특정 도구 카테고리만 활성화하기:

{
"mcpServers": {
"pipedrive": {
...

문제 해결을 위해 상세 로깅 (verbose logging) 활성화하기:

{
"mcpServers": {
"pipedrive": {
...

Claude, "Enterprise Software License"에 대해 50,000달러 가치의 새로운 딜 (deal)을 생성해줘.
연락처는 John Smith (john@acme.com)야. 예상 종료 날짜를 다음 달 말로 설정하고 내일로 후속 전화 (follow-up call)를 추가해줘.

Claude는 다음 작업을 수행합니다:

• "John Smith"라는 인물 (person)을 검색하거나 생성합니다.
• 이 인물과 연결된 딜 (deal)을 생성합니다.
• 내일로 전화 활동 (call activity)을 예약합니다.
• ID와 다음 단계가 포함된 요약을 제공합니다.

Acme Corporation에 있는 모든 연락처를 찾아서 그들의 최근 딜 (deals)을 보여줘.

Claude는 다음 작업을 수행합니다:

• 조직 (organizations)에서 "Acme Corporation"을 검색합니다.
• 해당 조직과 관련된 모든 인물 (persons)을 가져옵니다.
• 각 인물에 대한 딜 (deals)을 조회합니다.
• 합계와 함께 정리된 결과를 제시합니다.

내 진행 중인 딜 (open deals) 중 기한이 지난 모든 활동 (activities)을 보여주고 다음 주로 일정을 재조정해줘.

Claude는 다음 작업을 수행합니다:

• done=false인 모든 활동 (activities)을 나열합니다.

및 지난 마감일(past due dates) - 열려 있는 딜(deals)과 연결된 활동(activities) 필터링

• 다음 주 새로운 날짜로 각 활동 업데이트
• 재조정된 항목에 대한 요약 제공

이 딜을 생성하기 전에, 딜에 사용할 수 있는 커스텀 필드(custom fields)가 무엇인지 보여주고 각 필드의 의미를 설명해줘.

Claude는 다음 작업을 수행합니다:

• pipedrive://custom-fields 리소스에 접근
• 딜 전용 커스텀 필드 추출
• 필드 이름, 유형 및 옵션 표시
• 딜 생성 시 사용 방법 설명

내 영업 파이프라인(sales pipeline)의 각 단계별 딜 개수와 총 가치를 보여주는 파이프라인 보고서를 생성해줘.

Claude는 다음 작업을 수행합니다:

• pipedrive://pipelines 리소스 사용 - 단계별로 그룹화된 딜 요약 정보 가져오기
• 합계 및 백분율 계산
• 읽기 쉬운 보고서 형식으로 구성

주간 파이프라인 검토(weekly pipeline review) 프롬프트를 실행해줘.

Claude는 다음 작업을 수행합니다:

• weekly-pipeline-review 프롬프트 실행 - 단계별로 모든 열려 있는 딜 수집
• 지표 계산 (수주/실주(won/lost), 마감 임박, 정체된 딜)
• 실행 가능한 권장 사항 생성

딜(deals), 사람(persons), 조직(organizations), 제품(products) 또는 리드(leads)를 생성하거나 업데이트할 때 표시 이름(display name)을 통해 커스텀 필드 값을 전달하세요:

{
"title": "ACME Enterprise Deal",
"value": 50000,
...

MCP 서버는 이름을 Pipedrive 해시 키(hash keys)로 자동 변환합니다. 전체 가이드는 docs/CUSTOM_FIELDS.md를 참조하세요.

LLM에서 직접 파이프라인 단계(pipeline stages)와 리드 라벨(lead labels)을 관리하세요:

{ "name": "Qualified", "pipeline_id": 1, "deal_probability": 75 }

비동기 *_convert_to_* / *_convert_status 도구(tool) 쌍을 통해 적격 리드(qualified leads)를 딜로 변환하거나(또는 딜을 리드로 되돌리거나) 할 수 있습니다.

딜의 예약된 고정 결제(scheduled, fixed payments)를 관리하세요 (API v2 — 기존 구독(subscriptions) 기능을 대체하는 현대적인 방식):

{ "id": 123, "description": "Deposit", "amount": 500, "billing_date": "2026-01-15" }

도구(Tools): deals_list_installments, deals_add_installment, deals_update_installment, deals_delete_installment.

필드 도구(Field tools)는 이제 모든 엔티티를 지원합니다: deal, person, organization, product, lead 및 note 필드 목록 (fields_list_lead_fields, fields_list_note_fields — 읽기 전용), 그리고 API v2를 통한 완전한 project field CRUD (fields_list_project_fields, fields_create_project_field, fields_update_project_field, fields_delete_project_field).

PipedriveClient- 속도 제한 (rate limiting), 캐싱 (caching), 재시도 로직 (retry logic)이 포함된 HTTP 클라이언트
Rate Limiter- Bottleneck 기반 제한기 (10 req/s, burst capacity)
Cache Layer- LRU 제거 방식의 TTL 기반 캐시 (최대 500개 항목)
Retry Handler- 일시적인 오류에 대한 지수 백오프 (Exponential backoff)
Metrics Collector- 요청 추적 및 성능 모니터링
Error Handler- 컨텍스트를 포함한 표준화된 오류 형식화

각 도구는 일관된 패턴을 따릅니다:

Zod Schema- 설명이 포함된 오류를 제공하는 입력 유효성 검사 (Input validation)
Description- LLM을 위한 상세 사용 지침
Handler- PipedriveClient를 호출하는 비동기 함수 (Async function)

세 가지 MCP 리소스가 읽기 전용 참조 데이터를 제공합니다:

pipedrive://pipelines

• 단계(stages) 및 딜(deal) 개수가 포함된 모든 파이프라인 (pipelines)
  pipedrive://custom-fields
• 모든 엔티티에 대한 커스텀 필드 (custom field) 정의
  pipedrive://current-user
• 인증된 사용자 정보 및 권한

일반적인 작업을 위한 다섯 가지 가이드 워크플로우 (guided workflows):

create-deal-workflow

• person 및 activity를 포함한 완전한 딜 생성
  sales-qualification
• BANT 자격 검증 체크리스트
  follow-up-sequence
• 다일(multi-day) 활동 시퀀스
  weekly-pipeline-review
• 파이프라인 상태 보고서
  lost-deal-analysis
• 실주(lost deal) 패턴 분석

Default: 초당 10개 요청 (요청 간 100ms)
Burst: 매분 충전되는 100 토큰 저장소 (reservoir)
Auto-retry: 429 오류 발생 시 5초 후 자동 재시도

데이터 유형	TTL	이유
Pipelines	10분	파이프라인 구조는 드물게 변경됨
...

서버는 다음 사항을 추적합니다:

• 총 요청 수 및 성공률
• 평균 응답 시간
• 유형별 오류율
• 캐시 히트율 (Cache hit rate)
• 속도 제한 이벤트 (Rate limit events)

system/metrics 도구를 통해 메트릭(metrics)에 접근할 수 있습니다.

이 MCP 서버는 Pipedrive REST API v1을 구현합니다. 자세한 API 문서는 다음을 참조하세요:

엔티티(entities)를 생성하거나 업데이트하기 전에, 사용 가능한 커스텀 필드(custom fields)를 확인하십시오:

// MCP 리소스(resource)를 통해 접근
//custom-fields
// 또는 필드 도구(field tools) 사용
...

모든 도구는 다음과 같은 구조화된 오류(structured errors)를 반환합니다:

• 오류 유형 (validation, authentication, rate limit 등)
• 상세 메시지
• 권장 조치
• 원본 API 오류 (해당하는 경우)

복잡한 워크플로(workflows)를 위해 여러 도구를 체인(chain)으로 연결하여 사용하세요:

• 리드 자격 검증 (Lead Qualification)

  • 인물(person) 검색
  • 해당 인물의 딜(deals) 및 활동(activities) 가져오기
  • 자격 검증 노트 생성
  • 딜 단계(deal stage) 업데이트

• 딜 파이프라인 이동 (Deal Pipeline Movement)

  • 딜 상세 정보 가져오기
  • 커스텀 필드 요구사항 확인
  • 커스텀 필드 업데이트
  • 다음 단계로 이동
  • 다음 활동 생성

• 리포팅 (Reporting)

  • 단계별 딜 목록 나열
  • 딜 요약 정보 가져오기
  • 메트릭(metrics) 계산
  • 마크다운(markdown) 형식으로 포맷팅

일반적인 문제와 해결 방법은 TROUBLESHOOTING.md를 참조하세요.

빠른 해결 방법:

인증 오류 (Authentication errors): https://app.pipedrive.com/settings/api 에서 API 토큰을 확인하세요.
속도 제한 (Rate limiting): 요청 빈도를 줄이거나 캐싱(caching)을 활성화하세요.
유효성 검사 오류 (Validation errors): 도구 입력 스키마(schema)와 필수 필드를 확인하세요.
Claude에서 도구가 보이지 않는 경우: 설정 변경 후 Claude Desktop을 재시작하세요.

기여를 환영합니다! 가이드라인은 CONTRIBUTING.md를 참조해 주세요.

# 저장소(repository) 클론
git clone https://github.com/nubiia-dev/mcp-pipedrive.git
cd mcp-pipedrive
...

# 모든 테스트 실행
npm test
# 커버리지(coverage)와 함께 실행
...

보안 정책 및 취약점 보고 방법은 SECURITY.md를 참조하세요.

중요: API 토큰을 버전 관리 시스템(version control)에 절대 커밋하지 마세요. 항상 환경 변수(environment variables)를 사용하세요.

이 MCP 서버는 Nubiia에 의해 구축 및 유지 관리됩니다.

Nubiia는 기업이 프로세스를 자동화하고 도구를 AI와 통합할 수 있도록 지원합니다: 맞춤형 MCP 서버, CRM 및 ERP(Pipedrive, Holded 등) 연동, 그리고 비즈니스 데이터를 Claude와 같은 어시스턴트와 연결하는 에이전트가 그 예입니다. 이 @nubiia/mcp-pipedrive는 저희가 수행하는 작업의 오픈 소스 (open source) 예시입니다.

👉 귀하의 비즈니스를 위한 AI 통합 또는 자동화가 필요하신가요? nubiia.es · ✉️ hola@nubiia.es

이 프로젝트는 MIT 라이선스 (MIT License) 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

Holded CRM을 위한 훌륭한 MCP 서버 구현체인 mcp-holded에서 영감을 받았습니다.

Nubiia — AI 자동화 및 통합 (AI automation & integrations): nubiia.es
이슈 (Issues): GitHub Issues
토론 (Discussions): GitHub Discussions
문서 (Documentation): docs/

버전 기록 및 릴리스 노트는 CHANGELOG.md를 참조하세요.

• 실시간 업데이트를 위한 웹훅 (Webhook) 지원
• 대량 업데이트를 위한 일괄 작업 (Bulk operations)
• 복잡한 쿼리를 활용한 고급 필터링 (Advanced filtering)
• 내보내기/가져오기 (Export/import) 기능
• 다른 CRM과의 통합
• GraphQL 지원

Nubiia 제작 — nubiia.es · hola@nubiia.es

유지 관리자 (Maintainer): Samuel Fraga — GitHub

Nubiia의 헌신으로 제작되었습니다.