AI 어시스턴트를 Zammad에 연결하여 티켓, 사용자, 조직 및 첨부 파일을 관리할 수 있는 도구를 제공하는 MCP 서버입니다.

면책 조항: 이 프로젝트는 Zammad GmbH 또는 Zammad Foundation과 제휴하거나 보증을 받지 않습니다. 이는 Zammad API를 사용하는 독립적인 통합 솔루션입니다.

티켓 관리 (Ticket Management)zammad_search_tickets

• 다양한 필터를 사용하여 티켓 검색zammad_get_ticket

• 아티클(articles)을 포함한 상세 티켓 정보 가져오기 (페이지네이션 지원)zammad_create_ticket

• 새 티켓 생성zammad_update_ticket

• 티켓 속성 업데이트zammad_add_article

• 티켓에 댓글/노트 추가zammad_add_ticket_tag

/zammad_remove_ticket_tag

• 티켓 태그 관리zammad_get_ticket_tags

• 특정 티켓에 할당된 태그 가져오기zammad_list_tags

• 시스템에 정의된 모든 태그 목록 조회 (admin.tag 권한 필요)

첨부 파일 지원 (Attachment Support)zammad_get_article_attachments

• 티켓 아티클의 첨부 파일 목록 조회zammad_download_attachment

• 첨부 파일 내용 다운로드 (base64 인코딩)zammad_delete_attachment

• 티켓 아티클에서 첨부 파일 삭제

사용자 및 조직 관리 (User & Organization Management)zammad_get_user

/zammad_search_users

• 사용자 정보 및 검색zammad_get_organization

/zammad_search_organizations

• 조직 데이터zammad_get_current_user

• 인증된 사용자 정보 가져오기

시스템 정보 (System Information)zammad_list_groups

• 사용 가능한 모든 그룹 가져오기 (성능을 위해 캐싱됨)zammad_list_ticket_states

• 모든 티켓 상태 가져오기 (성능을 위해 캐싱됨)zammad_list_ticket_priorities

• 모든 우선순위 레벨 가져오기 (성능을 위해 캐싱됨)zammad_get_ticket_stats

• 티켓 통계 가져오기 (페이지네이션으로 최적화됨)

Zammad 데이터에 직접 액세스:

zammad://ticket/{id}

• 개별 티켓 상세 정보zammad://user/{id}

• 사용자 프로필 정보zammad://organization/{id}

• 조직 상세 정보zammad://queue/{group}

• 그룹별 티켓 큐

사전 구성된 프롬프트 (Pre-configured prompts):

analyze_ticket

• 종합적인 티켓 분석draft_response

• 티켓 응답 생성 (Generate ticket responses)

escalation_summary

• 에스컬레이션된 티켓 요약 (Summarize escalated tickets)

설치 없이 실행하기:

# 아직 설치하지 않았다면 uv를 설치하세요
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
...

프로덕션(Production) 또는 컨테이너화된 배포를 위한 경우:

# 환경 변수를 사용한 기본 사용법
docker run --rm -i \
-e ZAMMAD_URL=https://your-instance.zammad.com/api/v1 \
...

이 프로젝트는 유의적 버전(Semantic Versioning)을 사용하여 Docker 이미지를 배포합니다:

latest

• 가장 최근의 안정적인 릴리스 (Most recent stable release)

1.2.3

• 특정 버전 (프로덕션 환경에 권장)

1.2

• 1.2 마이너 릴리스의 최신 패치

1

• 1.x 메이저 릴리스의 최신 마이너/패치

main

• 최신 메인 브랜치 (불안정할 수 있음)

# 프로덕션 환경 권장 사항 - 특정 버전에 고정
docker pull ghcr.io/basher83/zammad-mcp:1.0.0

GitHub Container Registry에서 모든 버전을 확인하세요.

코드에 기여하거나 수정하려면:

# 저장소 복제 (Clone)
git clone https://github.com/basher83/zammad-mcp.git
cd zammad-mcp
...

수동 설정을 원하시면 아래의 개발(Development) 섹션을 참조하세요.

서버는 Zammad API 자격 증명(Credentials)이 필요합니다. .env 파일을 사용하세요:

예시 설정을 복사합니다:

cp .env.example .env

.env 파일을 편집합니다.

Zammad 자격 증명을 입력합니다:

필수: Zammad 인스턴스 URL (/api/v1 포함)

ZAMMAD_URL=https://your-instance.zammad.com/api/v1

인증 (한 가지 방법 선택):

옵션 1: API 토큰 (권장)

ZAMMAD_HTTP_TOKEN=your-api-token

옵션 2: OAuth2 토큰

ZAMMAD_OAUTH2_TOKEN=your-oauth2-token

옵션 3: 사용자 이름/비밀번호

ZAMMAD_USERNAME=your-username

ZAMMAD_PASSWORD=your-password

선택 사항: TLS 인증서 검증 비활성화 (운영 환경에서는 권장하지 않음)

Truthy 값만 허용: 1, true, yes, on. 설정하지 않으면 (기본값) TLS 검증이 활성화된 상태를 유지합니다.

ZAMMAD_INSECURE=true

선택 사항: 로깅 레벨 (기본값: INFO)

유효한 값: DEBUG, INFO, WARNING, ERROR, CRITICAL

LOG_LEVEL=INFO

선택 사항: 전송 구성 (Transport Configuration)

MCP_TRANSPORT=stdio

전송 유형: stdio (기본값) 또는 http

MCP_HOST=127.0.0.1 # HTTP 전송을 위한 호스트 주소

MCP_PORT=8000 # HTTP 전송을 위한 포트 번호

서버는 시작 시 자동으로 .env 파일을 로드합니다.

변수	기본값	설명
MCP_TRANSPORT	stdio	전송 유형: stdio 또는 http
MCP_HOST	127.0.0.1	HTTP 전송을 위한 호스트 주소
MCP_PORT	-	HTTP 전송을 위한 포트 번호 (MCP_TRANSPORT=http인 경우 필수)

중요: .env 파일을 버전 관리 시스템에 포함하지 마세요 (.gitignore에 이미 포함되어 있습니다).

데이터를 반환하는 모든 도구는 두 가지 출력 형식을 지원합니다:

Markdown(기본값): LLM 소비에 최적화된 사람이 읽기 쉬운 형식
JSON: 완전한 메타데이터를 포함한 기계가 읽기 쉬운 형식

예시:

# Markdown (기본값)
zammad_search_tickets(query="network", response_format="markdown")
# JSON
...

Claude Desktop 설정에 추가하세요:

{
"mcpServers": {
"zammad": {
...

또는 Docker를 사용하는 경우:

{
"mcpServers": {
"zammad": {
...

참고: 서버는 stdio (기본값) 및 HTTP 전송을 지원합니다. Stdio 모드를 Docker에서 사용하려면 -i 플래그가 필요합니다. 원격 배포에 대해서는 아래의 HTTP 전송 섹션을 참조하세요.

중요: -i

플래그가 필요합니다. 이 플래그가 없으면 MCP 서버가 stdin (표준 입력)을 받을 수 없습니다. 래퍼 스크립트 (wrapper scripts)나 셸 별칭 (shell aliases)에서 이 플래그를 유지하세요.

또는 로컬에 설치되어 있는 경우:

{
"mcpServers": {
"zammad": {
...

# 서버 실행
python -m mcp_zammad
# 또는 환경 변수와 함께 실행
...

서버는 원격 배포를 위해 Streamable HTTP 전송 (transport)을 지원합니다.

HTTP 전송을 활성화하려면 다음 환경 변수를 설정하세요:

export MCP_TRANSPORT=http # HTTP 전송 활성화
export MCP_HOST=127.0.0.1 # 바인딩할 호스트 (기본값: 127.0.0.1)
export MCP_PORT=8000 # 리슨할 포트

직접 Python 실행:

MCP_TRANSPORT=http \
MCP_HOST=127.0.0.1 \
MCP_PORT=8000 \
...

Docker:

docker run -d \
--name zammad-mcp-http \
-p 8000:8000 \
...

http://localhost:8000/mcp/에서 MCP 엔드포인트에 접속하세요.

보안 경고: 0.0.0.0에 바인딩하는 것은 TLS를 사용하는 리버스 프록시 (reverse proxy) 뒤에서만 수행해야 합니다.

HTTPS 및 보안을 위해 리버스 프록시 (nginx/Caddy)를 사용하세요:

Caddy 사용 예시:

# MCP 서버 시작 (리버스 프록시를 위해 모든 인터페이스에 바인딩)
MCP_TRANSPORT=http \
MCP_HOST=0.0.0.0 \
...

Caddyfile 설정:

mcp.yourdomain.com {
reverse_proxy localhost:8000
# Caddy가 HTTPS/TLS를 자동으로 처리합니다
...

운영 환경 체크리스트:

• MCP_HOST=0.0.0.0은 리버스 프록시 뒤에서만 사용하세요
• 리버스 프록시를 통해 HTTPS/TLS를 활성화하세요
• 프록시 또는 애플리케이션 계층에서 인증 (authentication)을 구현하세요
• 방화벽 규칙으로 액세스를 제한하세요

HTTP 전송을 사용하도록 MCP 클라이언트를 구성하세요:

{
"mcpServers": {
"zammad": {
...

로컬 개발: MCP_HOST=127.0.0.1 사용 (localhost 전용)
운영 환경: 인증 구현 (보안 섹션 참조)
HTTPS: TLS를 위해 리버스 프록시 사용
방화벽: 신뢰할 수 있는 네트워크로 액세스 제한
DNS Rebinding: 내장된 Origin 검증이 이러한 공격으로부터 보호합니다

state="open"과 함께 search_tickets를 사용하여 모든 열린 티켓을 찾으세요

다음과 함께 create_ticket을 사용하세요:
- title: "Customer needs help with login"
- group: "Support"
...

1. ticket_id=123과 함께 get_ticket을 사용하여 전체 대화 내용을 확인하세요
2. add_article을 사용하여 답변을 추가하세요
3. update_ticket을 사용하여 상태를 "pending reminder"로 변경하세요

escalation_summary 프롬프트를 사용하여 에스컬레이션(escalation)이 임박한 모든 티켓의 보고서를 받으세요

attachments 파라미터와 함께 add_article을 사용하세요:
- ticket_id: 123
- body: "첨부된 문서를 확인하세요"
...

delete_attachment을 다음 항목과 함께 사용하세요:
- ticket_id: 123
- article_id: 456
...

# 저장소(repository)를 클론합니다
git clone https://github.com/basher83/zammad-mcp.git
cd zammad-mcp
...

# 저장소(repository)를 클론합니다
git clone https://github.com/basher83/zammad-mcp.git
cd zammad-mcp
...

zammad-mcp/
├── mcp_zammad/
│ ├── __init__.py
...

# 개발 의존성(development dependencies)을 설치합니다
uv pip install -e ".[dev]"
# 테스트를 실행합니다
...

# 코드 포맷팅(Format code)
uv run ruff format mcp_zammad tests
# 린트(Lint)
...

Zammad에서 API 토큰(API token)을 생성하려면:

• Zammad 인스턴스에 로그인합니다

• 아바타 클릭 → 프로필(Profile)

• "Token Access"로 이동합니다

• "Create"를 클릭합니다

• 토큰의 이름을 지정합니다 (예: "MCP Server")

• 적절한 권한(permissions)을 선택합니다

• 생성된 토큰을 복사합니다

• Zammad URL에 프로토콜(https://)이 포함되어 있는지 확인합니다

• API 토큰에 필요한 권한이 있는지 확인합니다

• Zammad 인스턴스에 네트워크를 통해 접근 가능한지 확인합니다

• 자체 서명(self-signed)/내부 인증서의 경우에만: TLS 검증을 우회하려면
  ZAMMAD_INSECURE=true를 설정하세요

• 사용자 이름/비밀번호 대신 API 토큰을 사용하세요

• 토큰이 해당 작업에 필요한 권한을 가지고 있는지 확인하세요

• Zammad 설정에서 토큰 만료 여부를 확인하세요

서버는 Zammad의 속도 제한(rate limits)을 준수합니다. 속도 제한에 도달한 경우:

• 요청 빈도를 줄이세요
• 대규모 결과 세트에 대해 페이지네이션(Pagination)을 적용하세요
• 자주 액세스하는 데이터를 캐싱(Cache)하세요

서버는 업계 모범 사례(best practices)를 따라 여러 계층의 보호 기능을 구현합니다.

** ⚠️ 중요**: 보안 취약점에 대해 공개적인 GitHub 이슈(issue)를 생성하지 마세요.

GitHub Security Advisories를 통해 보고하거나(권장) SECURITY.md를 참조하세요.

• ✅
  입력값 검증 (Input Validation): 모든 사용자 입력을 검증 및 정제합니다 (models.py) - ✅
  SSRF 방지 (SSRF Protection): URL 검증을 통해 서버 측 요청 위조 (SSRF)를 방지합니다 (client.py) - ✅
  XSS 방지 (XSS Prevention): 모든 텍스트 필드의 HTML을 정제합니다 (models.py) - ✅
  보안 인증 (Secure Authentication): 비밀번호보다 API 토큰 사용을 권장합니다 (client.py) - ✅
  의존성 스캔 (Dependency Scanning): Dependabot이 취약점을 자동으로 탐지합니다 - ✅
  보안 테스트 (Security Testing): CI에서 Bandit, Safety, pip-audit를 실행합니다 (security-scan.yml)

전체 문서는 SECURITY.md를 참조하세요.

개발 환경 설정, 코드 표준, 테스트 및 풀 리퀘스트 (Pull Request) 가이드라인은 CONTRIBUTING.md를 참조하세요.

AGPL-3.0-or-later — Zammad 프로젝트 라이선스와 일치합니다.

• ARCHITECTURE.md — 기술 설계
• SECURITY.md — 보안 정책
• CONTRIBUTING.md — 개발 가이드라인
• CHANGELOG.md — 버전 이력

"Zammad"는 Zammad GmbH의 상표입니다. 이 독립적인 통합 라이브러리는 Zammad GmbH 또는 Zammad Foundation과 제휴하거나 승인되지 않았습니다. "Zammad"라는 명칭은 Zammad 티켓 시스템과의 호환성을 나타냅니다.