MFA ServiceNow MCP

Don’t script your AI. Arm it.

자연스럽게 AI에게 물어보세요.
나머지는 MCP 스킬이 알아서 처리합니다.

시작하기

GitHub

mfa-servicenow-mcp

개발 배경

ServiceNow 관리자를 위한 브라우저 인증 MCP가 없어서, 직접 만들었습니다.

ServiceNow 포털을 개발하면서 시작된 일입니다 — 위젯, 페이지, 스크립트 인클루드까지 얽힌 의존성 그래프요.
진짜 어려운 건 코드를 고치는 게 아니라, 뭐가 왜 깨졌는지 손대기 전에 정확히 진단하는 거였습니다.
AI 에이전트가 그 진단을 믿을 만하게 해낼 수 있다는 걸 확인하고 나니, 다음 질문은 자연스럽게 테스트와 배포까지 안전하게 맡길 수 있느냐였습니다.

그 진단을 위해서는 Table API만으로는 부족했습니다.
Flow Designer의 실제 구조 — 트리거, 액션, 플로우가 왜 실행됐는지 안 됐는지 — 는 일반 REST 인증으로는 닿을 수 없는 세션 전용 엔드포인트 뒤에 있습니다.
그래서 이 도구는 설정 파일에 박힌 API 키가 아니라 진짜 브라우저 인증으로 확장돼야 했습니다.
관리자에게 진짜 필요한 건 실제 관리자가 이미 갖고 있는 것 — MFA/SSO/SAML로 보호되는 진짜 세션입니다.
ServiceNow에 대해 이걸 해주는 MCP가 없길래, 그게 이 프로젝트의 핵심 구조가 됐습니다 — 에이전트는 키를 들고 있는 대신 살아있는 브라우저 세션을 그대로 물려받습니다.

거기서부터 이건 단순한 API 래퍼가 아니게 됐습니다.
모든 쓰기 작업은 숙련된 엔지니어가 손으로 직접 할 때와 같은 절차를 거칩니다 — 로컬 우선, 푸시 전에 라이브 서버와 diff, 충돌하는 수정은 조용히 덮어써지는 대신 잡아내도록 앵커링, 그리고 증명 가능함 — 배포 XML은 실제로 라이브 인스턴스에서 나왔다는 증명서를 함께 지니고 있습니다.

토큰 비용도 같은 취급을 받았습니다 — 모든 스키마는 압축되고, 모든 패키지는 에이전트가 실제로 쓸 수 있는 만큼만 노출됩니다.
여기 있는 모든 설계 결정은 스펙이 아니라 실제 ServiceNow 포털 업무에서 실전 검증을 거쳐 나온 것들입니다.

🔎 정확한 진단

어떤 위젯, 어떤 스크립트 인클루드, 어떤 플로우인지 — 스택 트레이스로 대충 짐작하는 대신 실제 의존성 체인을 추적합니다.

🔑 비밀 값이 아니라 세션

Flow Designer의 실제 구조는 Table API가 닿지 못하는 세션 전용 엔드포인트 뒤에 있습니다. 에이전트는 API 키 대신 살아있는 관리자 세션 — MFA, SSO, SAML —을 그대로 물려받습니다.

🧭 앵커링된 동기화

모든 푸시는 먼저 라이브 레코드와 diff되고 앵커링됩니다 — 충돌하는 수정은 조용히 덮어써지지 않고 잡힙니다.

🪶 설계 단계부터 토큰을 의식함

압축된 스키마, 패키지 단위 도구, 필요한 필드만 읽기 — 비용은 나중에 생각할 문제가 아니라 설계 제약입니다.

빠른 시작

이 한 줄만 복사하세요. 끝입니다.

아래 명령어를 AI 코딩 어시스턴트에 붙여넣으세요.
uv, Playwright, MCP 설정, 스킬 설치까지 한 번에 자동으로 설정됩니다.

Install and configure mfa-servicenow-mcp by following the instructions here:
curl -s https://raw.githubusercontent.com/jshsakura/mfa-servicenow-mcp/main/docs/llm-setup.md

Claude Code, Cursor, Codex, OpenCode, Windsurf, VS Code Copilot, Antigravity, Zed 등과 호환됩니다.
AI가 클라이언트와 OS를 감지한 뒤, 대화형으로 설정을 진행해 줍니다.
설정이 완료되면 AI 클라이언트를 재시작하여 MCP 서버를 로드하세요.

회사 보안툴이 uvx를 막는 환경이라면 아래 uvx가 막힐 때 (pip) 섹션을 참고하세요.

수동 설치 — 설치 + 설정

설치 후 클라이언트 설정에 추가

터미널에서 직접 하려면: uv + Chromium 설치 후, MCP 클라이언트 설정파일에 서버를 추가하세요(아래 예시).
별도 installer 명령도, 클라이언트별 플래그도 없습니다.

# 1. uv 설치 (이미 있으면 생략)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 서버 + Chromium 미리 받기 (첫 브라우저 호출에서 ~150 MB
#    받다가 timeout 나는 걸 예방)
uvx --refresh --with playwright --from mfa-servicenow-mcp servicenow-mcp --version
uvx --with playwright playwright install chromium

# 3. MCP 클라이언트 설정파일에 서버 추가 — 아래 예시 복사

# 1. uv 설치 (이미 있으면 생략)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 서버 + Chromium 미리 받기 (첫 브라우저 호출에서 ~150 MB
#    받다가 timeout 나는 걸 예방)
uvx --refresh --with playwright --from mfa-servicenow-mcp servicenow-mcp --version
uvx --with playwright playwright install chromium

# 3. MCP 클라이언트 설정파일에 서버 추가 — 아래 예시 복사

uvx가 막힐 때

pip으로 설치하기

Windows Smart App Control이 uvx를 차단합니다. uvx가 실행될 때마다 서명되지 않은 임시 실행 파일을 풀어내기 때문입니다. 얼마 전까지 잘 되던 uvx가 Windows 업데이트 직후부터 안 된다면 이게 원인입니다. pip으로 설치한 뒤 서버를 모듈로 실행하세요 — servicenow-mcp 콘솔 스크립트는 pip이 만들어 주는 서명 없는 .exe 래퍼라 같은 이유로 차단됩니다.

# Homebrew나 배포판 기본 Python은 전역 pip 설치를 거부합니다 (PEP 668).
# python.org 배포판을 쓰거나, 그냥 위의 uvx를 그대로 쓰세요.
pip install mfa-servicenow-mcp playwright
python -m playwright install chromium

# 확인:
python -m servicenow_mcp --version

# 나중에 업데이트할 때:
pip install --upgrade mfa-servicenow-mcp playwright
python -m playwright install chromium

# python.org의 Python 3.10+ 는 서명되어 있어 Smart App Control을 통과합니다.
pip install mfa-servicenow-mcp playwright
python -m playwright install chromium

# 확인:
python -m servicenow_mcp --version

# 나중에 업데이트할 때:
pip install --upgrade mfa-servicenow-mcp playwright
python -m playwright install chromium

env 블록은 어느 쪽이든 동일하고 command와 args만 달라집니다. 아래 수동 복구용 섹션의 스니펫을 붙여넣은 뒤, command를 python으로, args를 [“-m”, “servicenow_mcp”]로 지정하세요.

수동 복구용

클라이언트 설정을 직접 점검하거나 복구하기

installer가 권장 경로입니다. 아래 원시 설정 예시는 설정 파일을 직접 점검하거나 복구해야 할 때만 사용하세요.

구조는 4가지뿐 — env 블록은 어느 클라이언트에서나 동일합니다. 외부 래퍼만 다릅니다.

{
"mcpServers": {
  "servicenow": {
    "command": "uvx",
    "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"],
    "env": {
      "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser",
        "SERVICENOW_BROWSER_HEADLESS": "false",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password"
    }
  }
}
}

{
"servicenow": {
  "command": "uvx",
  "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"],
  "env": {
    "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser",
        "SERVICENOW_BROWSER_HEADLESS": "false",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password"
  }
}
}

[mcp_servers.servicenow]
command = "uvx"
args = ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"]
enabled = true

[mcp_servers.servicenow.env]
SERVICENOW_INSTANCE_URL = "https://your-instance.service-now.com"
SERVICENOW_AUTH_TYPE = "browser"
SERVICENOW_BROWSER_HEADLESS = "false"
SERVICENOW_USERNAME = "your-username"
SERVICENOW_PASSWORD = "your-password"

{
"$schema": "https://opencode.ai/config.json",
"mcp": {
  "servicenow": {
    "type": "local",
    "command": [
      "uvx", "--with", "playwright",
      "--from", "mfa-servicenow-mcp", "servicenow-mcp"
    ],
    "enabled": true,
    "environment": {
      "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser",
        "SERVICENOW_BROWSER_HEADLESS": "false",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password"
    }
  }
}
}

읽기 전용 standard 패키지가 기본 로드됩니다 — MCP_TOOL_PACKAGE를 적을 필요 없습니다. 쓰기 권한이 필요하면 어드밴스 패키지(service_desk, portal_developer, platform_developer, full)로 지정하세요 — 자세한 내용은 툴 패키지 (어드밴스) 가이드 참고.

수동 설치 — 3단계

LLM 최적화 스킬 추가하기

도구(Tool)만으로는 단순한 API 호출일 뿐입니다.
안전 장치, 롤백, 문맥 인식을 통한 위임 파이프라인이 포함된 스킬(Skill)들이 결합되었을 때
LLM은 진정으로 유용해집니다. 현재 4개 스킬을 지원하며 릴리스마다 더 추가되고 있습니다.

uvx --from mfa-servicenow-mcp servicenow-mcp-skills claude

uvx --from mfa-servicenow-mcp servicenow-mcp-skills codex

uvx --from mfa-servicenow-mcp servicenow-mcp-skills opencode

uvx --from mfa-servicenow-mcp servicenow-mcp-skills antigravity

🔍 analyze/

스킬 1개 — 로컬 소스 감사: 상호참조, 데드코드, 실행 순서, HTML 리포트

🧭 explore/

스킬 1개 — 플로우 트리거 추적: 테이블 변경 시 어떤 워크플로우/플로우가 실행되는지

📦 manage/

스킬 2개 — 앱 소스 다운로드, 로컬 동기화(diff → 충돌 탐지 후 푸시)

최신 버전 유지

항상 최신 버전으로 업데이트하기

uvx는 마지막으로 다운로드한 버전을 캐시하여 계속 재사용합니다 — 자동 업데이트되지 않습니다.
uv를 통해 업그레이드하세요:

uvx --refresh --from mfa-servicenow-mcp servicenow-mcp --version

업그레이드 후 MCP 클라이언트를 재시작해야 새 버전이 적용됩니다 (Claude Code, Cursor 등).

75등록 도구

MFA네이티브 지원

3스킬 패키지

0외부 공유되는 자격 증명

작동 방식

운영 환경까지 단 3단계

설정할 API 키나 구성 파일에 넣을 비밀번호가 없습니다.
브라우저를 통해 한 번만 인증하면 AI 에이전트가 실시간 세션을 상속받습니다.

설치

uvx를 사용한 명령 한 줄로 모든 설정이 끝납니다. 제로 구성(Zero config).

인증

실제 브라우저가 열려 조직에서 요구하는 MFA, SSO, SAML을 처리합니다.

연결

Claude, Cursor, Zed 또는 모든 MCP 클라이언트에 연결하세요. 등록 도구 75개가 활성 패키지 프로필을 통해 준비됩니다.

주요 기능

엔터프라이즈 환경에 맞게 구축됨

AI 에이전트와 ServiceNow를
대규모로 안전하게 연결하는 데 필요한 모든 것을 제공합니다.

🔒 제로 트러스트 보안

브라우저 기반 인증은 자격 증명이 절대 로컬 장치를 벗어나지 않음을 의미합니다. MFA, SSO, SAML 및 조직에서 사용하는 모든 로그인 흐름을 지원합니다.

⚡ 토큰 효율 성능

레이지 도구 디스커버리, 패키지별 스키마, 컴팩트 JSON, 응답 캐싱, 배치 조회로 startup과 LLM 컨텍스트 비용을 낮춥니다.

🧩 안전한 데이터 비교

선택형 named instance는 read-only dev/test drift 확인으로 제한됩니다. 일반 도구는 하나의 active 인스턴스에만 고정됩니다.

🤖 폭넓은 클라이언트 지원

Claude, Codex, Cursor, Zed, Antigravity, OpenCode, Windsurf, VS Code Copilot과 stdio/Streamable HTTP MCP 클라이언트에서 동작합니다.