ServiceNow MCP Server

ServiceNow MCP 서버

ServiceNow를 위한 MCP(모델 완성 프로토콜) 서버 구현으로 Claude가 ServiceNow 인스턴스와 상호 작용할 수 있습니다.

개요

이 프로젝트는 Claude가 ServiceNow 인스턴스에 연결하고, 데이터를 검색하고, ServiceNow API를 통해 작업을 수행할 수 있도록 하는 MCP 서버를 구현합니다. 이 서버는 Claude와 ServiceNow를 연결하는 다리 역할을 하여 원활한 통합을 가능하게 합니다.

특징

• 다양한 인증 방법(기본, OAuth, API 키)을 사용하여 ServiceNow 인스턴스에 연결합니다.
• ServiceNow 레코드 및 테이블 쿼리
• ServiceNow 레코드 생성, 업데이트 및 삭제
• ServiceNow 스크립트 및 워크플로 실행
• ServiceNow 서비스 카탈로그에 액세스하고 쿼리합니다.
• ServiceNow 서비스 카탈로그 분석 및 최적화
• 문제 해결을 위한 디버그 모드
• stdio 및 SSE(Server-Sent Events) 통신 모두 지원

설치

필수 조건

• Python 3.11 이상
• 적절한 액세스 자격 증명이 있는 ServiceNow 인스턴스

설정

1. 이 저장소를 복제하세요:지엑스피1
2. 가상 환경을 만들고 패키지를 설치하세요.
   python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install -e .
3. ServiceNow 자격 증명으로 .env 파일을 만듭니다.
   SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com SERVICENOW_USERNAME=your-username SERVICENOW_PASSWORD=your-password SERVICENOW_AUTH_TYPE=basic # or oauth, api_key

용법

표준(stdio) 모드

MCP 서버를 시작하려면:

또는 환경 변수를 사용하여:

서버 전송 이벤트(SSE) 모드

ServiceNow MCP 서버는 통신을 위해 SSE(Server-Sent Events)를 사용하는 웹 서버로도 실행될 수 있으므로 보다 유연한 통합 옵션이 제공됩니다.

SSE 서버 시작

제공된 CLI를 사용하여 SSE 서버를 시작할 수 있습니다.

기본적으로 서버는 0.0.0.0:8080 에서 수신 대기합니다. 호스트와 포트는 다음과 같이 설정할 수 있습니다.

SSE 서버에 연결

SSE 서버는 두 가지 주요 엔드포인트를 노출합니다.

• /sse - SSE 연결 엔드포인트
• /messages/ - 서버로 메시지를 보내기 위한 엔드포인트

예

SSE 서버를 설정하고 실행하는 방법에 대한 전체 예제는 examples/sse_server_example.py 파일을 참조하세요.

도구 포장(선택 사항)

언어 모델에 노출되는 도구 수를 관리하기 위해(특히 제한이 있는 환경에서), ServiceNow MCP 서버는 "패키지"라고 하는 도구 하위 집합의 로드를 지원합니다. 이는 MCP_TOOL_PACKAGE 환경 변수를 통해 제어됩니다.

구성

1. 환경 변수: MCP_TOOL_PACKAGE 환경 변수를 원하는 패키지 이름으로 설정합니다.
   export MCP_TOOL_PACKAGE=catalog_builder
2. 패키지 정의: 사용 가능한 패키지와 패키지에 포함된 도구는 config/tool_packages.yaml 파일에 정의되어 있습니다. 이 파일을 사용자 정의하여 원하는 패키지를 직접 만들 수 있습니다.

행동

• MCP_TOOL_PACKAGE 가 config/tool_packages.yaml 에 정의된 유효한 패키지 이름으로 설정된 경우 해당 패키지에 나열된 도구만 로드됩니다.
• MCP_TOOL_PACKAGE설정되지 않았 거나 비어 있으면 기본적으로 full 패키지(모든 도구 포함)가 로드됩니다.
• MCP_TOOL_PACKAGE 잘못된 패키지 이름으로 설정된 경우, none 패키지가 로드되고( list_tool_packages 외에는 도구가 없음) 경고가 기록됩니다.
• MCP_TOOL_PACKAGE=none 설정하면 도구( list_tool_packages 제외)를 명시적으로 로드하지 않습니다.

사용 가능한 패키지(기본값)

기본 config/tool_packages.yaml 에는 다음과 같은 역할 기반 패키지가 포함되어 있습니다.

• service_desk : 사고 처리 및 기본 사용자/지식 조회를 위한 도구입니다.
• catalog_builder : 서비스 카탈로그 항목, 카테고리, 변수 및 관련 스크립팅(UI 정책, 사용자 기준)을 만들고 관리하는 도구입니다.
• change_coordinator : 작업 및 승인을 포함하여 변경 요청 수명 주기를 관리하기 위한 도구입니다.
• knowledge_author : 지식 기반, 카테고리, 문서를 만들고 관리하는 도구입니다.
• platform_developer : 서버 측 스크립팅(스크립트 포함), 워크플로 개발 및 배포(변경 세트)를 위한 도구입니다.
• system_administrator : 사용자/그룹 관리 및 시스템 로그 보기 도구입니다.
• full : 사용 가능한 모든 도구가 포함됩니다(기본값).
• none : 도구를 포함하지 않습니다( list_tool_packages 제외).

내성 도구

• list_tool_packages : 구성에 정의된 사용 가능한 모든 도구 패키지 이름을 나열하고 현재 로드된 패키지를 표시합니다. 이 도구는 none 제외한 모든 패키지에서 사용할 수 있습니다.

사용 가능한 도구

참고: 다음 도구의 사용 가능 여부는 로드된 도구 패키지에 따라 다릅니다(위의 도구 패키징 섹션 참조). 기본적으로( full 패키지) 모든 도구를 사용할 수 있습니다.

사고 관리 도구

1. create_incident - ServiceNow에서 새로운 인시던트를 생성합니다.
2. update_incident - ServiceNow에서 기존 인시던트 업데이트
3. add_comment - ServiceNow에서 인시던트에 주석을 추가합니다.
4. resolve_incident - ServiceNow에서 인시던트 해결
5. list_incidents - ServiceNow의 인시던트 목록

서비스 카탈로그 도구

1. list_catalog_items - ServiceNow에서 서비스 카탈로그 항목 나열
2. get_catalog_item - ServiceNow에서 특정 서비스 카탈로그 항목을 가져옵니다.
3. list_catalog_categories - ServiceNow에서 서비스 카탈로그 범주 나열
4. create_catalog_category - ServiceNow에서 새 서비스 카탈로그 범주를 만듭니다.
5. update_catalog_category - ServiceNow에서 기존 서비스 카탈로그 범주를 업데이트합니다.
6. move_catalog_items - ServiceNow에서 카테고리 간 카탈로그 항목 이동
7. create_catalog_item_variable - 카탈로그 항목에 대한 새 변수(양식 필드)를 만듭니다.
8. list_catalog_item_variables - 카탈로그 항목의 모든 변수를 나열합니다.
9. update_catalog_item_variable - 카탈로그 항목의 기존 변수 업데이트
10. list_catalogs - ServiceNow의 서비스 카탈로그 나열

카탈로그 최적화 도구

1. get_optimization_recommendations - 서비스 카탈로그 최적화를 위한 권장 사항 받기
2. update_catalog_item - 서비스 카탈로그 항목 업데이트

변경 관리 도구

1. create_change_request - ServiceNow에서 새로운 변경 요청을 만듭니다.
2. update_change_request - 기존 변경 요청 업데이트
3. list_change_requests - 필터링 옵션을 사용하여 변경 요청 나열
4. get_change_request_details - 특정 변경 요청에 대한 자세한 정보를 가져옵니다.
5. add_change_task - 변경 요청에 작업 추가
6. submit_change_for_approval - 승인을 위해 변경 요청 제출
7. approve_change - 변경 요청 승인
8. reject_change - 변경 요청 거부

워크플로 관리 도구

1. list_workflows - ServiceNow의 워크플로 목록
2. get_workflow - ServiceNow에서 특정 워크플로 가져오기
3. create_workflow - ServiceNow에서 새 워크플로를 만듭니다.
4. update_workflow - ServiceNow에서 기존 워크플로 업데이트
5. delete_workflow - ServiceNow에서 워크플로 삭제

스크립트에는 관리 도구가 포함됩니다.

1. list_script_includes - ServiceNow에서 포함하는 스크립트 목록
2. get_script_include - ServiceNow에서 특정 스크립트 포함 가져오기
3. create_script_include - ServiceNow에 새 스크립트 포함을 만듭니다.
4. update_script_include - ServiceNow에 포함된 기존 스크립트를 업데이트합니다.
5. delete_script_include - ServiceNow에서 스크립트 포함을 삭제합니다.

변경 세트 관리 도구

1. list_changesets - 필터링 옵션을 사용하여 ServiceNow의 변경 세트 나열
2. get_changeset_details - 특정 변경 세트에 대한 자세한 정보를 가져옵니다.
3. create_changeset - ServiceNow에서 새 변경 집합을 만듭니다.
4. update_changeset - 기존 변경 세트 업데이트
5. commit_changeset - 변경 세트 커밋
6. publish_changeset - 변경 세트 게시
7. add_file_to_changeset - 변경 세트에 파일 추가

지식 기반 관리 도구

1. create_knowledge_base - ServiceNow에서 새로운 지식 기반을 만듭니다.
2. list_knowledge_bases - 필터링 옵션을 사용하여 지식 기반 나열
3. create_category - 지식베이스에 새로운 카테고리를 만듭니다.
4. create_article - ServiceNow에서 새로운 지식 문서 만들기
5. update_article - ServiceNow에서 기존 지식 문서 업데이트
6. publish_article - ServiceNow에 지식 문서 게시
7. list_articles - 필터링 옵션을 사용하여 지식 문서 나열
8. get_article - ID로 특정 지식 문서 가져오기

사용자 관리 도구

1. create_user - ServiceNow에서 새 사용자 생성
2. update_user - ServiceNow에서 기존 사용자 업데이트
3. get_user - ID, 사용자 이름 또는 이메일로 특정 사용자를 가져옵니다.
4. list_users - 필터링 옵션을 사용하여 사용자 목록 표시
5. create_group - ServiceNow에서 새 그룹을 만듭니다.
6. update_group - ServiceNow에서 기존 그룹 업데이트
7. add_group_members - ServiceNow에서 그룹에 멤버 추가
8. remove_group_members - ServiceNow에서 그룹에서 멤버 제거
9. list_groups - 필터링 옵션이 있는 그룹 목록

UI 정책 도구

1. create_ui_policy - 일반적으로 카탈로그 항목에 대한 ServiceNow UI 정책을 만듭니다.
2. create_ui_policy_action - 변수 상태(표시 여부, 필수 등)를 제어하기 위해 UI 정책과 연관된 작업을 만듭니다.

MCP CLI 사용

ServiceNow MCP 서버는 MCP CLI를 통해 설치할 수 있으며, 이를 통해 Claude에 서버를 편리하게 등록할 수 있습니다.

이 명령은 ServiceNow MCP 서버를 Claude에 등록하고 .env 파일의 환경 변수를 사용하도록 구성합니다.

Claude Desktop과 통합

Claude Desktop에서 ServiceNow MCP 서버를 구성하려면:

1. ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 해당 OS에 맞는 경로에서 Claude Desktop 구성 파일을 편집합니다.

2. 변경 사항을 적용하려면 Claude Desktop을 다시 시작하세요.

Claude를 사용한 예시 사용

다음은 MCP 서버를 통해 ServiceNow와 상호 작용하기 위해 Claude와 함께 사용할 수 있는 몇 가지 자연어 쿼리 예시입니다.

사고 관리 사례

• "동부 지역의 네트워크 중단에 대한 새로운 인시던트를 생성합니다"
• "인시던트 INC0010001의 우선순위를 높음으로 업데이트"
• "INC0010001 사건에 문제가 조사 중이라는 주석을 추가하세요."
• "서버가 다시 시작되었다는 메모와 함께 인시던트 INC0010001을 해결하세요."
• "네트워크 팀에 할당된 모든 높은 우선 순위 사건을 나열하세요"
• "네트워크 팀에 할당된 모든 활성 P1 인시던트를 나열하세요."

서비스 카탈로그 예

• "서비스 카탈로그의 모든 항목을 보여주세요"
• "모든 서비스 카탈로그 카테고리 나열"
• "노트북 요청 카탈로그 항목에 대한 세부 정보 가져오기"
• "하드웨어 카테고리의 모든 카탈로그 항목을 보여주세요"
• "서비스 카탈로그에서 '소프트웨어'를 검색하세요"
• "서비스 카탈로그에 '클라우드 서비스'라는 새 카테고리를 만듭니다."
• "하드웨어" 카테고리를 업데이트하여 이름을 "IT 장비"로 변경합니다.
• "가상 머신" 카탈로그 항목을 "클라우드 서비스" 범주로 이동합니다.
• "IT 장비" 카테고리 아래에 "모니터"라는 하위 카테고리를 만듭니다.
• "모든 소프트웨어 항목을 '소프트웨어' 카테고리로 이동하여 카탈로그를 재구성하세요."
• "노트북 요청 카탈로그 항목에 대한 설명 필드 만들기"
• "카탈로그 항목에 노트북 모델을 선택하기 위한 드롭다운 필드 추가"
• "VPN 액세스 요청 카탈로그 항목에 대한 모든 양식 필드를 나열하세요"
• "소프트웨어 요청 양식에서 부서 필드를 필수로 지정하세요"
• "비용 센터 필드에 대한 도움말 텍스트를 업데이트합니다"
• "시스템의 모든 서비스 카탈로그를 보여주세요"
• "모든 하드웨어 카탈로그 항목을 나열하세요."
• "'신규 노트북 요청' 카탈로그 항목을 찾으세요."
• '새 노트북 요청' 항목에 대한 변수를 보여주세요.
• '신입 사원 채용' 카탈로그 항목에 대해 '부서 코드'라는 새 변수를 만듭니다. 필수 문자열 필드로 지정합니다.

카탈로그 최적화 예

• "서비스 카탈로그를 분석하고 개선 기회를 파악하세요"
• "개선이 필요한 설명이 부족한 카탈로그 항목을 찾으세요"
• "사용률이 낮아 폐기할 가능성이 있는 카탈로그 항목을 식별합니다."
• "포기율이 높은 카탈로그 항목 찾기"
• "사용자 경험을 개선하기 위해 하드웨어 카테고리를 최적화하세요"

변경 관리 사례

• "내일 밤 보안 패치를 적용하기 위해 서버 유지 관리를 위한 변경 요청을 작성하세요"
• "다음 화요일 오전 2시부터 오전 4시까지 데이터베이스 업그레이드를 예약하세요"
• "사전 구현 확인을 위해 서버 유지 관리 변경에 작업 추가"
• "승인을 위해 서버 유지 관리 변경 사항을 제출하세요"
• "데이터베이스 업그레이드 변경 사항을 승인합니다. 설명: 구현 계획이 철저해 보입니다."
• "이번 주에 예약된 모든 긴급 변경 사항을 보여주세요"
• "네트워크 팀에 할당된 모든 변경 사항을 나열하세요"
• "프로덕션 데이터베이스 서버를 업그레이드하기 위한 일반적인 변경 요청을 만듭니다."
• "변경 사항 CHG0012345를 업데이트하고 상태를 '구현'으로 설정합니다."

워크플로 관리 예

• "ServiceNow의 모든 활성 워크플로를 보여주세요"
• "인시던트 승인 워크플로에 대한 세부 정보 가져오기"
• "변경 요청 워크플로의 모든 버전을 나열합니다"
• "서비스 카탈로그 요청 워크플로의 모든 활동을 보여주세요"
• "소프트웨어 라이선스 요청 처리를 위한 새로운 워크플로우 만들기"
• "인시던트 에스컬레이션 워크플로에 대한 설명을 업데이트하세요"
• "신입사원 온보딩 워크플로 활성화"
• "이전 비밀번호 재설정 워크플로 비활성화"
• "소프트웨어 라이선스 요청 워크플로에 승인 활동 추가"
• "인시던트 에스컬레이션 워크플로에서 알림 활동 업데이트"
• "변경 요청 워크플로에서 불필요한 활동을 삭제하세요"
• "서비스 카탈로그 요청 워크플로에서 활동 재정렬"

변경 세트 관리 예

• "ServiceNow의 모든 변경 세트 나열"
• "개발자 'john.doe'가 만든 모든 변경 세트를 보여주세요"
• "변경 세트 'sys_update_set_123'에 대한 세부 정보 가져오기"
• "HR Portal" 애플리케이션에 대한 새 변경 세트를 만듭니다.
• "변경 세트 'sys_update_set_123'에 대한 설명을 업데이트합니다."
• "로그인 문제 해결" 메시지와 함께 변경 세트 'sys_update_set_123'을 커밋합니다.
• "프로덕션에 'sys_update_set_123' 변경 세트를 게시합니다."
• "변경 세트 'sys_update_set_123'에 파일을 추가합니다."
• "변경 세트 'sys_update_set_123'의 모든 변경 사항을 보여주세요"

지식 기반 예시

• "IT 부서를 위한 새로운 지식 기반을 만드세요"
• "조직의 모든 지식 기반을 나열하세요"
• "IT 지식 기반에 '네트워크 문제 해결'이라는 범주를 만듭니다."
• "네트워크 문제 해결 카테고리에 VPN 설정에 대한 기사를 작성하세요"
• "모바일 기기 지침을 포함하도록 VPN 설정 문서를 업데이트하세요"
• "모든 사용자가 볼 수 있도록 VPN 설정 문서를 게시하세요"
• "네트워크 문제 해결 카테고리의 모든 문서 나열"
• "VPN 설정 문서의 세부 정보를 보여주세요"
• "IT 지식 기반에서 '비밀번호 재설정'이 포함된 지식 문서 찾기"
• "네트워크 문제 해결 범주 아래에 '무선 네트워크'라는 하위 범주를 만듭니다."

사용자 관리 예

• "방사선과에서 Dr. Alice Radiology라는 새 사용자를 만드세요"
• "Bob의 사용자 기록을 업데이트하여 그를 Alice의 관리자로 만듭니다."
• "Bob에게 ITIL 역할을 할당하여 변경 요청을 승인할 수 있도록 하세요."
• "방사선과 부서의 모든 사용자를 나열하세요"
• "의료기기 관리를 위한 '생체공학'이라는 새로운 그룹을 만들어라"
• "생체공학 그룹에 관리자 사용자를 멤버로 추가합니다."
• "생체공학 그룹에 관리자를 변경하도록 업데이트하세요"
• "생체공학 그룹에서 사용자 제거"
• "시스템에서 직함에 '의사'가 포함된 모든 활성 사용자를 찾으세요"
• "방사선과 부서의 승인자 역할을 할 사용자를 생성하세요"
• "시스템의 모든 IT 지원 그룹을 나열하세요"

UI 정책 예시

• "'소프트웨어 요청' 항목(sys_id: abc...)에 대해 'software_cost'가 100보다 클 때 적용되는 '정당성 표시'라는 UI 정책을 만듭니다."
• UI 정책 '정의 표시'(sys_id: def...)에 대해 'business_justification' 변수를 표시하고 필수로 만드는 작업을 추가합니다.
• "'alternative_software' 변수를 숨기려면 '정당 표시' 정책에 대한 다른 작업을 만듭니다."

예제 스크립트

저장소에는 도구 사용 방법을 보여주는 예제 스크립트가 포함되어 있습니다.

• examples/catalog_optimization_example.py : ServiceNow 서비스 카탈로그를 분석하고 개선하는 방법을 보여줍니다.
• examples/change_management_demo.py : ServiceNow에서 변경 요청을 생성하고 관리하는 방법을 보여줍니다.

인증 방법

기본 인증

OAuth 인증

API 키 인증

개발

선적 서류 비치

추가 문서는 docs 디렉토리에서 확인할 수 있습니다.

• 카탈로그 통합 - 서비스 카탈로그 통합에 대한 자세한 정보
• 카탈로그 최적화 - 카탈로그 최적화 기능에 대한 상세 계획
• 변경 관리 - 변경 관리 도구에 대한 자세한 정보
• 워크플로 관리 - 워크플로 관리 도구에 대한 자세한 정보
• 변경 집합 관리 - 변경 집합 관리 도구에 대한 자세한 정보

문제 해결

변경 관리 도구의 일반적인 오류

1. 오류: argument after ** must be a mapping, not CreateChangeRequestParams
   • 이 오류는 create_change_request 함수에 사전 대신 CreateChangeRequestParams 객체를 전달할 때 발생합니다.
   • 해결 방법: Pydantic 모델 객체가 아닌 매개변수가 포함된 사전을 전달하고 있는지 확인하세요.
   • 참고: 변경 관리 도구가 이 오류를 자동으로 처리하도록 업데이트되었습니다. 이제 함수는 매개변수가 잘못 래핑되었거나 Pydantic 모델 객체로 전달된 경우 매개변수의 래핑을 해제하려고 시도합니다.
2. 오류: Missing required parameter 'type'
   • 이 오류는 변경 요청을 만드는 데 필요한 모든 매개변수를 제공하지 않으면 발생합니다.
   • 해결 방법: 필수 매개변수를 모두 포함해야 합니다. create_change_request 의 경우, short_description 과 type 모두 필수입니다.
3. 오류: Invalid value for parameter 'type'
   • 이 오류는 type 매개변수에 잘못된 값을 제공할 때 발생합니다.
   • 해결 방법: 유효한 값 중 하나를 사용하세요: "normal", "standard", 또는 "emergency".
4. 오류: Cannot find get_headers method in either auth_manager or server_config
   • 이 오류는 매개변수가 잘못된 순서로 전달되거나 필요한 메서드가 없는 객체를 사용할 때 발생합니다.
   • 해결 방법: auth_manager 및 server_config 매개변수를 올바른 순서대로 전달했는지 확인하세요. 매개변수 교체를 자동으로 처리하도록 함수가 업데이트되었습니다.

기여하다

기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.

1. 저장소를 포크하세요
2. 기능 브랜치를 생성합니다( git checkout -b feature/amazing-feature )
3. 변경 사항을 커밋하세요( git commit -m 'Add some amazing feature' )
4. 브랜치에 푸시( git push origin feature/amazing-feature )
5. 풀 리퀘스트 열기

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.