servicenow-mcp

AI 에이전트가 Table API를 통해 ServiceNow 인시던트를 생성, 검색 및 업데이트할 수 있게 해주는 작은 MCP 서버입니다. 공식 Python mcp 패키지(FastMCP 스타일 데코레이터), httpx 및 python-dotenv로 구축되었습니다. stdio를 통해 실행됩니다.

모든 것은 단일 파일 server.py에 있습니다.

설정

Python 3.12+ 및 uv가 필요합니다.

uv sync

인스턴스에 대한 기본 인증 자격 증명을 사용하여 server.py 옆에 .env를 만듭니다(이는 git에서 무시됩니다). Personal Developer Instance가 잘 작동합니다:

SNOW_INSTANCE_URL=https://devXXXXXX.service-now.com
SNOW_USERNAME=admin
SNOW_PASSWORD=your-password
# optional, default 15
SNOW_TIMEOUT_SECONDS=15

서버를 실행합니다(서버는 stdin/stdout을 통해 MCP를 사용하므로 표시할 내용이 없습니다. MCP 클라이언트가 실행해야 합니다):

uv run server.py

MCP 클라이언트에 등록

.venv와 .env가 선택되도록 프로젝트 디렉토리와 함께 uv를 가리키도록 클라이언트를 설정합니다:

{
  "mcpServers": {
    "servicenow": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/servicenow-mcp", "run", "server.py"]
    }
  }
}

Claude Code의 경우: claude mcp add servicenow -- uv --directory /absolute/path/to/servicenow-mcp run server.py.

클라이언트 환경에 이미 설정된 환경 변수는 .env보다 우선합니다.

Related MCP server: sn-mcp-bridge

도구

모든 도구는 스택 추적 대신 읽을 수 있는 도구 오류(에이전트에 isError로 표시됨)를 발생시킵니다. 예:

• 인증 실패 (401): SNOW_USERNAME 및 SNOW_PASSWORD를 확인하세요. ServiceNow 응답: 사용자가 인증되지 않았습니다 …

• https://…에 연결할 수 없습니다: [Errno 8] nodename nor servname provided … SNOW_INSTANCE_URL 및 네트워크 연결을 확인하세요.

• https://…와 통신하는 동안 15초 후 시간 초과되었습니다. 인스턴스가 최대 절전 모드(PDI)이거나 연결할 수 없습니다.

• 인시던트 'INC9999999'를 https://…에서 찾을 수 없습니다.

• 금지됨 (403): 사용자에게 권한이 없거나 … 비즈니스 규칙에 의해 업데이트가 거부되었습니다. ServiceNow 응답: … (예: 해결 필드 없이 인시던트를 해결하는 경우).

설계 노트

• ServiceNowClient 는 단일 httpx.AsyncClient(기본 인증, JSON 헤더, 시간 초과)를 래핑하고 create_record / query_records / get_record_by_number / update_record를 노출합니다. 모든 오류는 사람이 읽을 수 있는 메시지와 함께 ServiceNowError로 변환됩니다.

• 도구는 get_client()를 통해 클라이언트를 가져옵니다. 테스트에서 set_client(fake)를 호출하여 네트워크에 접촉하지 않고 모의 객체로 교체합니다.

• 레코드는 sysparm_display_value=all로 가져오므로 상태/긴급 레이블은 하드코딩된 맵 대신 인스턴스 자체에서 가져옵니다(친숙한 이름 별칭은 입력 전용입니다).

• mcp 2.x는 FastMCP를 MCPServer로 이름을 변경했습니다. server.py는 둘 중 존재하는 것을 가져오므로 1.x와 2.x 모두에서 실행됩니다.

간이 테스트

라이브 인스턴스에 대해 실행합니다(하나의 인시던트를 작성합니다):

uv run python -c "
import asyncio, server
async def main():
    c = await server.create_incident('MCP server smoke test', 'created by smoke test')
    print(c)
    print(await server.query_incidents(query_text='MCP server smoke test'))
    print(await server.update_incident(c['number'], work_notes='hello from MCP'))
asyncio.run(main())
"