freshservice-mcp

AI 어시스턴트를 Freshservice ITSM 인스턴스에 연결하는 MCP(Model Context Protocol) 서버입니다. 자연어를 통해 티켓, 자산, 변경, 문제, 서비스 카탈로그, 지식 베이스 등을 관리하세요.

기능

9개 카테고리에 걸친 53개의 도구:

카테고리	도구	설명
티켓	9	목록, 조회, 생성, 업데이트, 삭제, 회신, 메모 추가, 대화 내용, 검색
자산	5	목록, 조회, 생성, 업데이트, 삭제
사용자	8	요청자, 상담원, 그룹, 부서 (목록 + 조회)
티켓 작업	5	티켓의 하위 작업 목록, 조회, 생성, 업데이트, 삭제
시간 기록	4	시간 로그 목록, 생성, 업데이트, 삭제
변경	5	변경 요청 목록, 조회, 생성, 업데이트, 삭제
문제	5	문제 레코드 목록, 조회, 생성, 업데이트, 삭제
서비스 카탈로그	3	카탈로그 항목 탐색, 세부 정보 조회, 서비스 요청 제출
지식 베이스	9	카테고리, 폴더, 문서 (전체 CRUD)

빠른 시작

사전 요구 사항

Node.js 18 이상
API 액세스 권한이 있는 Freshservice 계정
Freshservice API 키 (프로필 아이콘 > 프로필 설정 > 오른쪽 패널의 API 키)

npx를 통한 설치 (권장)

설치가 필요 없습니다. MCP 클라이언트를 구성하여 다음을 실행하세요:

{
  "mcpServers": {
    "freshservice": {
      "command": "npx",
      "args": ["-y", "freshservice-mcp"],
      "env": {
        "FRESHSERVICE_DOMAIN": "yourcompany",
        "FRESHSERVICE_API_KEY": "your-api-key"
      }
    }
  }
}

전역 설치

npm install -g freshservice-mcp

그런 다음 MCP 클라이언트를 구성하세요:

{
  "mcpServers": {
    "freshservice": {
      "command": "freshservice-mcp",
      "env": {
        "FRESHSERVICE_DOMAIN": "yourcompany",
        "FRESHSERVICE_API_KEY": "your-api-key"
      }
    }
  }
}

소스에서 설치

git clone https://github.com/tannertm0/freshservice-mcp.git
cd freshservice-mcp
npm install

{
  "mcpServers": {
    "freshservice": {
      "command": "node",
      "args": ["/path/to/freshservice-mcp/src/index.js"],
      "env": {
        "FRESHSERVICE_DOMAIN": "yourcompany",
        "FRESHSERVICE_API_KEY": "your-api-key"
      }
    }
  }
}

구성

변수	필수	설명
`FRESHSERVICE_DOMAIN`	예	Freshservice 하위 도메인 (예: `yourcompany.freshservice.com`의 경우 `yourcompany`)
`FRESHSERVICE_API_KEY`	예	Freshservice API 키

MCP 클라이언트 설정

Claude Desktop - ~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)에 추가하세요.

Claude Code - claude mcp add freshservice -- npx -y freshservice-mcp를 실행한 후 환경 변수를 설정하세요.

Cursor / VS Code - 편집기 문서에 따라 MCP 설정에 추가하세요.

사용 가능한 도구

티켓

도구	설명
`list_tickets`	필터(상태, 우선순위, 요청자, 날짜)를 사용하여 티켓 목록 조회
`get_ticket`	전체 티켓 세부 정보 조회
`create_ticket`	새 티켓 생성
`update_ticket`	티켓 필드(상태, 우선순위, 담당자 등) 업데이트
`delete_ticket`	티켓 삭제 (휴지통으로 이동)
`reply_to_ticket`	티켓에 회신 전송
`add_note_to_ticket`	공개 또는 비공개 메모 추가
`get_ticket_conversations`	모든 회신 및 메모 보기
`search_tickets`	쿼리 구문을 사용하여 티켓 필터링

자산

도구	설명
`list_assets`	모든 자산/CI 목록 조회
`get_asset`	사용자 지정 필드를 포함한 자산 세부 정보 조회
`create_asset`	새 자산 등록
`update_asset`	자산 필드 업데이트
`delete_asset`	자산 제거

사용자 및 조직

도구	설명
`list_requesters` / `get_requester`	최종 사용자
`list_agents` / `get_agent`	지원 담당자
`list_groups` / `get_group`	구성원이 포함된 상담원 그룹
`list_departments` / `get_department`	부서

티켓 작업

도구	설명
`list_ticket_tasks`	티켓의 하위 작업 목록 조회
`get_ticket_task`	작업 세부 정보 조회
`create_ticket_task`	티켓에 작업 추가
`update_ticket_task`	작업 상태/담당자 업데이트
`delete_ticket_task`	작업 제거

시간 기록

도구	설명
`list_time_entries`	티켓에 기록된 시간 보기
`create_time_entry`	소요 시간 기록
`update_time_entry`	시간 기록 수정
`delete_time_entry`	시간 기록 제거

변경

도구	설명
`list_changes`	변경 요청 목록 조회
`get_change`	변경 세부 정보(유형, 위험, 일정) 조회
`create_change`	변경 요청 생성
`update_change`	변경 필드 업데이트
`delete_change`	변경 삭제

문제

도구	설명
`list_problems`	문제 레코드 목록 조회
`get_problem`	문제 세부 정보 조회
`create_problem`	문제 레코드 생성
`update_problem`	문제 필드 업데이트
`delete_problem`	문제 삭제

서비스 카탈로그

도구	설명
`list_service_catalog_items`	사용 가능한 서비스 탐색
`get_service_catalog_item`	서비스 세부 정보 및 필수 필드 조회
`place_service_request`	서비스 요청 제출

지식 베이스

도구	설명
`list_solution_categories` / `get_solution_category`	KB 카테고리 탐색
`list_solution_folders` / `get_solution_folder`	KB 폴더 탐색
`list_solution_articles` / `get_solution_article`	문서 읽기
`create_solution_article`	새 문서 작성
`update_solution_article`	문서 편집
`delete_solution_article`	문서 제거

예시 프롬프트

구성이 완료되면 AI 어시스턴트에게 다음과 같이 요청할 수 있습니다:

"모든 오픈 P1 티켓을 보여줘"
"3층 프린터가 오프라인 상태라는 티켓을 생성해줘"
"John Smith에게 할당된 자산은 무엇인가요?"
"티켓 #5678에 공급업체를 기다리고 있다는 비공개 메모를 추가해줘"
"다음 주 화요일로 예정된 방화벽 업그레이드에 대한 변경 요청을 생성해줘"
"지식 베이스에서 VPN 설정 지침을 검색해줘"
"네트워크 문제 디버깅을 위해 티켓 #1234에 2시간을 기록해줘"
"모든 오픈 문제와 그 영향 수준을 보여줘"
"서비스 카탈로그에서 새 노트북 요청을 제출해줘"

검색 쿼리 구문

search_tickets 도구는 Freshservice의 필터 쿼리 구문을 사용합니다:

"priority:4 AND status:2"          - Urgent + Open tickets
"group_id:12345"                   - Tickets assigned to a specific group
"agent_id:67890"                   - Tickets assigned to a specific agent
"created_at:>'2024-01-01'"         - Tickets created after a date

개발

git clone https://github.com/tannertm0/freshservice-mcp.git
cd freshservice-mcp
npm install
npm test

라이선스

MIT

Freshservice MCP Server