servicenow-mcp

ServiceNow 인시던트를 Table API를 통해 관리하는 MCP 서버입니다. 인시던트 생성, 읽기, 업데이트, 검색, 댓글 추가, 해결을 위한 도구를 제공합니다.

설정

1. 의존성 설치:

   uv sync

2. .env.example을 .env로 복사하고 자격 증명을 입력:

   cp .env.example .env

   • SERVICENOW_INSTANCE: 인스턴스 이름만 입력 (예: dev12345.service-now.com의 경우 dev12345)

   • SERVICENOW_USERNAME / SERVICENOW_PASSWORD: incident 테이블에 접근 권한이 있는 사용자의 기본 인증 자격 증명 (Table API를 통한 읽기/쓰기)

3. 서버를 직접 실행하여 정상 시작 확인:

   uv run servicenow-mcp

Related MCP server: servicenow-api

Claude Desktop / Claude Code와 함께 사용하기

연결 방법은 두 가지입니다. 서버를 사용하는 모든 사람이 하나의 ServiceNow 서비스 계정을 공유할지, 아니면 각자가 자신의 계정으로 인증할지에 따라 선택합니다. 전체 내용은 인증을 참조하세요.

옵션 A — stdio, 공유 서비스 계정

클라이언트가 서버를 하위 프로세스로 직접 실행합니다. 모든 도구 호출은 env를 통해 전달된 SERVICENOW_USERNAME / SERVICENOW_PASSWORD를 사용합니다.

{
  "mcpServers": {
    "servicenow": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/servicenow-mcp", "run", "servicenow-mcp"],
      "env": {
        "SERVICENOW_INSTANCE": "your-instance",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password"
      }
    }
  }
}

옵션 B — HTTP, 클라이언트별 자격 증명

서버를 한 번 실행하여 장기 실행 HTTP 프로세스로 유지합니다 (SERVICENOW_INSTANCE만 필요하며, 인증 헤더가 없는 요청을 위한 대체로 SERVICENOW_USERNAME/PASSWORD도 필요):

uv run servicenow-mcp --transport streamable-http --host 127.0.0.1 --port 8003

그런 다음 .mcp.json에서 이를 가리키고 자신의 ServiceNow 로그인을 HTTP Basic Auth 헤더로 보냅니다. 이것이 연결을 "클라이언트 수준"으로 만드는 핵심입니다. 자격 증명은 서버가 아닌 클라이언트 설정에 저장됩니다:

{
  "mcpServers": {
    "servicenow": {
      "type": "http",
      "url": "http://127.0.0.1:8003/mcp",
      "headers": {
        "Authorization": "Basic <base64 of your-username:your-password>"
      }
    }
  }
}

터미널에서 base64 값을 생성합니다 (echo의 -n이 앞 공백을 방지함):

echo -n "your-username:your-password" | base64

.mcp.json은 .env와 달리 .gitignore에 포함되지 않습니다. 이 디렉토리가 공유/git 저장소가 될 경우 실제 자격 증명을 커밋하지 마세요.

도구

• create_incident — 새 인시던트 생성

• get_incident — 번호(예: INC0010023) 또는 sys_id로 조회

• update_incident — 임의 필드 업데이트

• search_incidents — ServiceNow 인코딩 쿼리(sysparm_query)로 검색

• add_comment — 고객이 볼 수 있는 댓글 또는 내부 작업 메모 추가

• resolve_incident — 상태를 해결됨으로 설정하고 종료 메모/코드 추가

인증

인증은 기본 인증(사용자 이름/비밀번호)입니다. 자격 증명의 출처는 전송 방식에 따라 다릅니다:

• stdio: 항상 .env의 공유 SERVICENOW_USERNAME / SERVICENOW_PASSWORD를 사용합니다.

• HTTP (sse / streamable-http): 각 요청은 표준 HTTP Basic Auth 헤더를 보내 자신의 ServiceNow 사용자로 인증할 수 있습니다:

  Authorization: Basic base64(username:password)

  SERVICENOW_INSTANCE는 서버 측에 유지됩니다(모든 클라이언트에 대해 하나의 인스턴스). 그러나 사용자 이름/비밀번호는 클라이언트별로 다릅니다. 따라서 search_incidents 결과, caller_id 확인 등은 하나의 공유 서비스 계정 대신 해당 개별 사용자의 ServiceNow 권한을 반영합니다. 요청에 Authorization 헤더가 없으면 .env의 공유 SERVICENOW_USERNAME / SERVICENOW_PASSWORD로 대체됩니다.

나중에 OAuth 2.0이 필요하면 src/servicenow_mcp/client.py의 requests.Session.auth 설정을 토큰 기반 흐름으로 교체하세요. 나머지 클라이언트는 인증 방식에 영향을 받지 않습니다.

참고 사항

• 인시던트 테이블의 state 필드는 숫자입니다 (예: 6 = 해결됨, 7 = 종료됨). 인스턴스에서 인시던트 상태를 사용자 정의한 경우 값이 다를 수 있습니다.