ServiceNow MCP 보고서

로컬 MCP 서버로, 두 개의 온디맨드 ServiceNow 보고서를 제공합니다. [[ServiceNow MCP Server — Syslog & Dev Work Reports (Plan)]]의 계획을 기반으로 구축되었습니다. 설정 설명과 문제 해결 방법도 볼트에 있습니다: [[ServiceNow MCP Server — Syslog & Dev Work Reports (Setup Guide)]].

현재 두 도구를 넘어 확장하는 아이디어는 echelon-ai-labs/servicenow-mcp를 참조하세요 — 훨씬 더 큰 Python/FastMCP ServiceNow 서버입니다 (인시던트, 변경, 카탈로그, 지식 베이스, 스크립트 인클루드, Agile 도구). 이미 이 프로젝트에서 차용한 것: stdio와 함께 원격 접근 가능한 HTTP 전송 (7단계) — 해당 저장소는 stdio와 SSE를 모두 노출합니다; 그리고 날짜 범위 필터는 ServiceNow 자체의 상대 날짜 키워드(ONLast week@javascript:gs.beginningOfLastWeek()@javascript:gs.endOfLastWeek())를 사용하여 리터럴 날짜/시간을 직접 구성하지 않습니다 — 이 패턴을 이 프로젝트의 자체 쿼리와 비교한 것이 아래 4단계/문제 해결에서 수정된 시간대 버그를 발견하게 했습니다. 아직 차용하지 않은 것: AuthManager — 하나의 인터페이스 뒤에서 Basic/OAuth/API-key를 지원합니다 (이 프로젝트는 Basic만 지원).

도구

둘 다 Table API에 대한 읽기 전용 GET 쿼리입니다 — 어떤 도구도 인스턴스에 쓰지 않습니다. 둘 다 원시/그룹화된 행만 반환합니다; 분석(제안된 수정, 플래그된 우려)은 도구 내부가 아니라 Claude와의 대화에서 이루어집니다. 둘 다 하드코딩된 단일 페이지 sysparm_limit 대신 자동으로 페이지를 매깁니다 (servicenow-client.ts의 queryTableAll, 페이지당 1000행, 10,000행 안전 상한) — 쿼리가 상한에 도달하면 응답은 JSON 앞에 명시적인 ⚠ Truncated 텍스트 블록을 먼저 표시하며, 조용히 부분 보고서를 반환하지 않습니다. 두 진입점 모두 동일한 src/create-server.ts에서 등록됩니다.

get_syslog_report

단일 날짜의 syslog 행을 가져오며, 기본적으로 경고/오류로 필터링됩니다.

다음의 JSON 배열을 반환합니다:

{
  "sys_created_on": "2026-08-25 17:30:24",
  "message": "SG-Azure Request failed with statusCode: 403 Code: AccessDenied ...",
  "source": "sn_sg_azure_integ",
  "level": "2",
  "node": "..."
}

get_developer_work_report

두 날짜 사이의 sys_update_xml 변경 사항을 가져오며, 작성자와 업데이트 세트별로 그룹화합니다.

다음의 JSON 배열을 반환합니다:

{
  "author": "system",
  "updateSet": "Default",
  "isDefaultUpdateSet": true,
  "changeCount": 2,
  "changes": [
    { "name": "...", "type": "Service Graph Connections State", "created": "2026-08-25 10:30:30" }
  ]
}

Related MCP server: ServiceNow MCP Server

1. 읽기 전용 ServiceNow 서비스 계정 프로비저닝 (수동, 1회)

PDI (https://dev203275.service-now.com)에서 관리자로 로그인하여 수행합니다:

1. User Administration → Users → New

   • User ID: claude_mcp_readonly

   • 비밀번호를 설정하고 "Password needs reset" 체크를 해제합니다.

   • **"Web service access only"**를 체크합니다 — 필수. 이 옵션이 없으면 ServiceNow의 SNCRestrictBasicAuthUserAuthenticationGate가 이 계정에 대해 REST를 통한 Basic Auth를 차단합니다. 비밀번호가 정확해도 마찬가지입니다. 계정이 대화형 UI 로그인도 허용되기 때문입니다. 놓친 경우의 증상: 동일한 자격 증명으로 UI에 로그인하면 정상인데 모든 REST 호출이 "User is not authenticated"로 401을 반환합니다. 문제 해결을 참조하세요.

2. 해당 사용자 레코드에서 → Roles 관련 목록 → Edit → 추가:

   • rest_api_explorer (REST API 액세스)

   • syslog 및 sys_update_xml/sys_update_set에 대한 읽기 액세스 — PDI에서는 snc_read_only 또는 내장 itil 역할이 일반적으로 이를 포함합니다. 역할 이름을 가정하지 말고 사용자가 실제로 해당 테이블을 읽을 수 있는지 확인하세요 (아래 3단계 참조).

   • admin을 부여하지 마세요 — 원래 계획에 따라 이 계정은 항상 쿼리만 해야 합니다.

3. .env.example을 .env로 복사하고 SN_USER / SN_PASS에 이 새 계정을 입력합니다.

2. 빌드

cd C:\Users\willr\projects\servicenow-mcp-reports
npm install
npm run build

3. 클라이언트에 연결하기 전에 자격 증명 확인

$env:SN_INSTANCE="https://dev203275.service-now.com"; $env:SN_USER="claude_mcp_readonly"; $env:SN_PASS="<password>"
node -e "fetch(process.env.SN_INSTANCE+'/api/now/table/sys_user?sysparm_limit=1',{headers:{Authorization:'Basic '+Buffer.from(process.env.SN_USER+':'+process.env.SN_PASS).toString('base64')}}).then(r=>console.log(r.status))"

200이 출력되어야 합니다. 401이면 비밀번호를 확인하고, 403이면 역할이 아직 해당 테이블을 포함하지 않는 것입니다.

4. syslog 테이블 이름, 레벨 값 및 날짜 필터링 (해결됨)

2026-08-26에 이 인스턴스에서 확인됨:

• 테이블은 **syslog**이며 sys_log가 아닙니다 (sys_log는 400 Invalid table sys_log를 반환합니다).

• syslog.level은 숫자이며 문자열 "warning"/"error"가 아닙니다: -2=Trace, -1=Debug, 0=Information, 1=Warning, 2=Error, 3=Fatal (GET /api/now/table/sys_choice?sysparm_query=name=syslog^element=level로 확인됨).

• 날짜 범위 필터는 일반 리터럴 날짜/시간 ('<date> 00:00:00'@'<date> 23:59:59')을 사용해야 하며 javascript:gs.dateGenerate(...)가 아닙니다 — 후자가 결과를 조용히 잘못된 날짜로 이동시킨 이유는 문제 해결을 참조하세요.

src/tools/syslog.ts는 친숙한 레벨 이름 ("warning", "error" 등)을 내부적으로 이러한 코드에 매핑하므로 호출자는 계속 이름을 전달할 수 있습니다 — 이는 도구를 확장하거나 다른 인스턴스를 가리킬 때만 중요하며, 매핑은 동일한 sys_choice 쿼리로 다시 확인해야 합니다.

5. Claude Code CLI에 등록

claude mcp add --scope user servicenow-reports -- "C:\Program Files\nodejs\node.exe" C:\Users\willr\projects\servicenow-mcp-reports\dist\index.js

node.exe의 절대 경로를 사용하세요. 단순한 node가 아니라 — Node가 PATH에 있기 전에 시작된 Claude Code 세션은 서버를 생성할 때 단순한 node 명령을 해석할 수 없습니다 (claude mcp list에 CONNECTION_CLOSED가 표시됩니다). claude mcp list로 확인하세요.

Claude Code CLI는 이 프로젝트 폴더의 .env에서 SN_INSTANCE/SN_USER/SN_PASS를 읽습니다 — 여기에 .env가 존재하는 한 CLI 쪽에서 추가 환경 구성이 필요하지 않습니다. 이는 src/index.ts가 .env의 경로를 컴파일된 스크립트 자체(import.meta.url)를 기준으로 해석하는 데 의존합니다. process.cwd()가 아닙니다 — 단순한 import "dotenv/config"는 실패합니다. Claude Code가 이 서버를 관련 없는 작업 디렉토리에서 생성하기 때문입니다. .env가 로드되지 않는 것 같으면 문제 해결을 참조하세요.

6. Claude Desktop에 등록

%APPDATA%\Claude\claude_desktop_config.json에 추가합니다 (새로 생성됨 — 이 머신에는 존재하지 않았습니다):

{
  "mcpServers": {
    "servicenow-reports": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\willr\\projects\\servicenow-mcp-reports\\dist\\index.js"],
      "env": {
        "SN_INSTANCE": "https://dev203275.service-now.com",
        "SN_USER": "claude_mcp_readonly",
        "SN_PASS": "<password>"
      }
    }
  }
}

Desktop은 이 프로젝트의 .env를 상속하지 않고 서버를 자체 프로세스로 실행하므로 자격 증명이 여기에 명시적으로 반복됩니다. 편집 후 Claude Desktop을 다시 시작한 다음 🔌 커넥터 아이콘을 확인하여 연결되었는지 확인하세요.

7. 선택 사항: 원격 접근 가능한 HTTP 전송

5–6단계는 stdio를 사용하며, 이는 로컬 프로세스를 생성할 수 있는 클라이언트(Claude Code, Claude Desktop)에서만 작동합니다. 그렇지 않은 클라이언트 — 예: claude.ai의 호스팅된 Scheduled Tasks — 는 HTTP 엔드포인트가 필요합니다. src/http.ts는 MCP의 Streamable HTTP 전송을 통해 POST/GET /mcp에서 동일한 두 도구를 노출합니다.

npm run build
$env:MCP_HTTP_TOKEN="<pick something random>"; npm run start:http

기본값: 127.0.0.1:3535에 바인딩됩니다 (.env의 MCP_HTTP_HOST / MCP_HTTP_PORT로 재정의 가능). MCP_HTTP_TOKEN이 설정된 경우 모든 요청은 Authorization: Bearer <token>을 보내야 하며 그렇지 않으면 401을 받습니다. 설정되지 않은 경우 서버는 경고를 기록하고 인증되지 않은 요청을 수락합니다 — localhost에만 바인딩된 동안에는 괜찮지만 공용 터널 뒤에 있게 되면 괜찮지 않습니다. createMcpExpressApp() (SDK에서)은 localhost 호스트에 바인딩될 때마다 DNS 리바인딩 보호를 자동으로 활성화합니다.

claude.ai의 호스팅된 Scheduled Tasks에서 실제로 이 서버에 도달하려면 127.0.0.1로는 충분하지 않습니다 — 공용 URL이 필요합니다 (예: 터널: ngrok http 3535, 또는 실제 배포). 이는 별도의 단계이며 여기서는 수행하지 않습니다. 이는 단지 기능을 추가할 뿐입니다. 먼저 로컬에서 스모크 테스트를 수행하세요:

curl.exe -s -X POST http://127.0.0.1:3535/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer $env:MCP_HTTP_TOKEN" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoketest","version":"0.0.1"}}}'

200과 mcp-session-id 응답 헤더 및 JSON-RPC result 본문을 반환해야 합니다.

문제 해결

• 비밀번호가 정확한데도 모든 REST 호출에서 401이 발생하지만 동일한 자격 증명으로 ServiceNow UI에 로그인하면 작동하는 경우 — 이는 SNCRestrictBasicAuthUserAuthenticationGate 때문입니다: 대화형 로그인도 가능한 계정에 대해 REST를 통한 Basic Auth를 차단합니다. 해결책: 사용자 레코드에서 **"Web service access only"**를 체크하세요 (1단계). 비밀번호 재설정에 시간을 낭비하지 마세요 — 해당 패턴 (UI 로그인은 정상, REST 401, "User is not authenticated" / "Required to provide Auth information")은 이 게이트 때문이지 잘못된 자격 증명이 아닙니다. System Logs (/syslog_list.do, 계정 이름으로 필터)에서 직접 진단할 수 있습니다.

• Invalid table sys_log (HTTP 400) — 테이블은 syslog이며 밑줄이 없습니다.

• 해당 날짜에 로그가 존재하는데도 보고서가 비어서 반환되는 경우 — 이 인스턴스에서 level은 숫자입니다 (4단계 참조), 문자열 "warning"/"error"가 아닙니다. 다른 인스턴스를 가리키는 경우 sys_choice 쿼리를 통해 매핑을 다시 확인하세요.

• 실제 MCP 서버로 실행할 때 Missing SN_INSTANCE, SN_USER, or SN_PASS environment variables" 오류가 발생하지만, .env가 존재하고 이 폴더에서 직접 node dist/index.js 테스트는 정상 작동하는 경우 — 직접 테스트가 성공하는 이유는 process.cwd()가 우연히 프로젝트 폴더이기 때문입니다. Claude Code는 다른 위치에서 서버를 실행하므로 단순한 dotenv/config는 조용히 실패합니다. src/index.ts가 .env를 cwd가 아닌 import.meta.url로 해석하는지 확인하세요 (5단계 참조). 항상 실제 MCP 도구 호출로 검증하세요. 직접 스크립트 실행만으로는 안 됩니다 — 둘은 다를 수 있습니다.

• get_syslog_report가 조용히 잘못된 날짜를 반환하거나 몇 시간이 누락되는 경우 — 실제 버그였으며, 2026-08-26에 echelon-ai-labs/servicenow-mcp의 쿼리 패턴과 대조하여 발견되었습니다. src/tools/syslog.ts는 날짜 필터를 sys_created_onBETWEENjavascript:gs.dateGenerate('<date>','00:00:00')@javascript:gs.dateGenerate(...)로 구성했습니다. gs.dateGenerate()는 인스턴스의 구성된 시간대에서 평가되지만 sys_created_on은 Table API를 통해 원시 UTC 값으로 반환됩니다 — 따라서 창이 인스턴스의 UTC 델타(이 PDI에서 약 7시간)만큼 조용히 이동하여 잘못된 날짜의 끝부분을 포함하고 올바른 날짜의 초기 시간을 누락했습니다. javascript:gs.dateGenerate(...) 래퍼를 완전히 제거하고 일반 리터럴 '<date> 00:00:00'@'<date> 23:59:59' 문자열을 전달하여 수정했습니다. 이는 시간대 변환 없이 원시 저장 값과 직접 비교됩니다. 확인: 2026-08-25의 24시간 전체에 걸쳐 834행, 수정 전 17시간에 걸쳐 366행. 이 인스턴스의 시간대 구성이 변경되면 가정하지 말고 동일한 전체 시간 범위 검사(4단계 스타일의 스팟 체크)로 다시 확인하세요.

• claude mcp list에서 CONNECTION_CLOSED — CLI 세션이 Node.js가 PATH에 있기 전에 시작되었습니다. node.exe의 절대 경로로 등록하거나 (5단계에서 이미 수행) 새 세션을 시작하세요.

• 코드를 편집하고 다시 빌드했지만 동작이 변경되지 않는 경우 — 이미 실행 중인 Claude Code 세션은 stdio 연결을 통해 이전 dist/를 유지합니다. 해당 세션에서 /mcp를 실행하여 다시 연결하세요. 재시작은 필요 없습니다.

파일

• src/servicenow-client.ts — Table API 래퍼 (Basic Auth) 및 queryTableAll, 두 도구가 사용하는 페이지네이션 루프 (페이지당 1000행, 10,000행 안전 상한, { rows, truncated } 반환). 나중에 PDI에서 벗어날 경우 여기서 Basic Auth를 OAuth로 교체하세요.

• src/tools/syslog.ts, src/tools/dev-work-report.ts — 두 보고서 쿼리.

• src/create-server.ts — McpServer를 구축하고 두 도구를 등록합니다. 아래 두 진입점에서 공유됩니다.

• src/index.ts — stdio 진입점 (Claude Code/Desktop); .env를 자신 기준으로 해석합니다 (cwd 아님).

• src/http.ts — Streamable HTTP 진입점 (7단계); bearer-token 인증, 세션당 하나의 서버+전송.