MCP 클라이언트 설정¶

각 MCP 클라이언트별 상세 설정 가이드입니다. 모든 클라이언트는 동일한 MCP 서버를 사용하며, 설정 형식만 다릅니다.

먼저 권장하는 방법: servicenow-mcp setup <client> --instance-url ...를 실행하거나 llm-setup.ko.md의 AI 자동 설치 흐름을 사용하세요. 아래 설정 예시는 MCP 설정을 직접 점검하거나 수동 복구해야 할 때 참고하는 용도입니다.

시작하기 전에¶

먼저 uv를 설치하세요. Python, 패키지, 실행을 한번에 처리합니다. MCP 서버는 uvx로 실행되며 uv가 필요합니다.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

설치 후 터미널을 재시작하세요. Python 설치, pip, venv 전부 필요 없습니다.

MFA/SSO 브라우저 로그인용 Chromium은 첫 사용 시 자동 설치됩니다. Windows 사용자: Windows 설치 가이드에서 단계별 안내를 확인하세요.

동작 확인¶

클라이언트 설정 전에 서버가 정상 작동하는지 먼저 확인하세요:

uvx --with playwright --from mfa-servicenow-mcp servicenow-mcp \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type "browser" \
  --browser-headless "false"

서버가 시작되고 로그인용 브라우저 창이 열리면, 아래 클라이언트 설정으로 넘어갈 준비가 된 것입니다.

설정 가이드¶

args는 패키지 실행에만 사용합니다. 인스턴스 URL, 인증 방식, 자격 증명은 모두 env(또는 environment)에 넣으세요. 이렇게 하면 args가 깔끔하게 유지되고, 프로젝트별로 다른 인스턴스에 쉽게 연결할 수 있습니다.

프로젝트 로컬 설정을 권장합니다: 프로젝트 단위로 설정하면 각 프로젝트가 서로 다른 ServiceNow 인스턴스에 연결할 수 있습니다.

Claude Desktop¶

범위	경로
전역	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
전역	`%APPDATA%\Claude\claude_desktop_config.json` (Windows)

{
  "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",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

Claude Desktop은 프로젝트 로컬 설정을 지원하지 않습니다. 프로젝트별 설정이 필요하면 Claude Code를 사용하세요.

Claude Code¶

범위	경로
전역	`~/.claude.json`
프로젝트	프로젝트 루트의 `.mcp.json`

{
  "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",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

Zed¶

범위	경로
전역	`~/.config/zed/settings.json`

Zed에서 Settings > MCP Servers로 추가하세요:

{
  "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_TOOL_PACKAGE": "standard"
    }
  }
}

OpenAI Codex (CLI & App)¶

Codex CLI(codex 명령어)와 Codex App(chatgpt.com/codex) 모두 동일한 config.toml을 사용합니다.

범위	경로	비고
전역	`~/.codex/config.toml`	모든 프로젝트에 공통 적용
프로젝트	`.codex/config.toml`	전역 설정을 덮어씀 (신뢰하는 프로젝트만)

[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"
MCP_TOOL_PACKAGE = "full"

OpenCode¶

범위	경로
프로젝트	프로젝트 루트의 `opencode.json`

OpenCode는 env 대신 environment를 사용합니다.

{
  "$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",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

Gemini CLI¶

범위	경로
전역	`~/.gemini/settings.json`
프로젝트	프로젝트 루트의 `.gemini/settings.json`

{
  "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",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

AntiGravity¶

범위	경로
전역	`~/.gemini/antigravity/mcp_config.json` (macOS/Linux)
전역	`%USERPROFILE%\.gemini\antigravity\mcp_config.json` (Windows)

에이전트 패널에서도 수정할 수 있습니다: ... > Manage MCP Servers > View raw config. 저장 후 Refresh를 클릭하세요.

{
  "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",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

Docker (API Key만 지원)¶

브라우저 인증(MFA/SSO)은 GUI 브라우저가 필요하여 컨테이너 환경에서는 동작하지 않습니다.

docker run -it --rm \
  -e SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com \
  -e SERVICENOW_AUTH_TYPE=api_key \
  -e SERVICENOW_API_KEY=your-api-key \
  -e MCP_TOOL_PACKAGE=standard \
  ghcr.io/jshsakura/mfa-servicenow-mcp:latest