sn-mcp-bridge

경량 Model Context Protocol (MCP) 서버로, AI 코딩 어시스턴트에게 ServiceNow에서 완전한 개발 기능을 제공합니다. 별도의 설치가 필요 없습니다. npx를 통해 로컬에서 실행되며 Table API를 통해 ServiceNow에 연결됩니다.

ServiceNow는 레코드 기반 개발 플랫폼입니다. Script Include, Business Rule, Client Script, UI Action, ACL 등 모든 개발 산출물은 시스템 테이블의 레코드입니다. 별도의 '코드 레이어'는 없으며, Table API 자체가 개발 API입니다. 즉, 이 서버를 통한 CRUD 작업은 단순히 데이터를 조회하는 것이 아니라 개발을 수행하는 수단입니다:

• sys_script_include에 insert_record → 새 Script Include 생성

• sys_script에 update_record → Business Rule 수정

• sys_script_client에 query_data → 특정 테이블의 모든 Client Script 조회

• sys_ui_action에 delete_record → UI Action 제거

CRUD를 넘어서는 작업(로직 테스트, 복잡한 GlideRecord 쿼리 실행, Script Include 호출, 다단계 트랜잭션)의 경우 execute_script가 완전한 서버 측 JavaScript 런타임을 제공합니다.

서버는 사용자가 제공한 자격 증명의 권한으로 실행됩니다. 사용자가 접근 권한이 있는 테이블과 필드만 읽고 쓸 수 있습니다. execute_script 도구는 sys.scripts.do를 통해 Background Script를 실행하므로 관리자 자격 증명이 필요합니다.

인증은 Basic Auth와 **OAuth 2.0 (Authorization Code)**을 모두 지원합니다. 자세한 내용은 인증을 참조하세요.

커뮤니티에서 공유되는 오픈소스 ServiceNow MCP 서버가 많습니다. 이 서버는 단순하고 순수하며 개선하기 쉽게 유지하기 위해 존재합니다. 빌드 단계가 없는 일반 JS(4개의 소스 파일, 기본 fetch, Node.js 18+)이며, 도구 추가는 server.registerTool() 호출 한 번이면 됩니다.

도구

CRUD

스키마 및 검색

분석

고급

진단

¹ 이 네 가지 도구는 사용자 이름과 비밀번호가 필요합니다. 인증을 참조하세요. OAuth 자격 증명만 구성된 경우 등록되지 않습니다.

Related MCP server: ServiceNow MCP Server

인증

브릿지는 두 가지 모드를 지원합니다. CLIENT_ID, CLIENT_SECRET, GRANT_TYPE이 설정되면 OAuth를 선택하고, 그렇지 않으면 Basic Auth를 사용합니다.

모든 변수는 동일한 명명 규칙을 따릅니다: <INSTANCE_NAME>은 SN_INSTANCE의 서브도메인으로, 하이픈을 밑줄로 바꾸고 대문자로 변환합니다(예: https://mydev01.service-now.com → SN_MYDEV01_USERNAME). 접두사가 있는 변수가 설정되지 않으면 브릿지는 접두사가 없는 형식(SN_USERNAME, SN_CLIENT_ID, …)으로 대체됩니다.

Basic Auth

경고: 아래 예제는 빠른 시작을 위해 일반 텍스트 자격 증명을 사용합니다. 즉, 비밀번호가 디스크의 파일에 저장되고 또한 LLM 제공자에 대한 모든 API 호출에서 AI 어시스턴트에게 표시됩니다. 연결이 작동하는 것을 확인한 후에는 Secretless AI로 자격 증명 보호 지침에 따라 일반 텍스트 비밀을 구성에서 제거하는 것이 좋습니다!

OAuth 2.0 (Authorization Code)

OAuth는 ServiceNow 비밀번호를 구성에서 완전히 제외합니다. 브릿지는 브라우저를 통해 한 번 인증한 후, 수명이 짧은 액세스 토큰을 자동으로 갱신합니다.

1. ServiceNow에서 OAuth 애플리케이션을 등록합니다. 시스템 OAuth → 애플리케이션 레지스트리로 이동하여 새로 만들기를 클릭하고 외부 클라이언트를 위한 OAuth API 엔드포인트 생성을 선택합니다. 이름을 지정하고 리디렉션 URL을 http://localhost:33380/callback으로 설정한 후 저장합니다. 생성된 클라이언트 ID와 클라이언트 시크릿을 복사합니다.

2. 브릿지를 구성합니다:

CLIENT_ID / CLIENT_SECRET / GRANT_TYPE 중 하나만 설정하고 나머지를 설정하지 않으면 자동으로 Basic Auth로 대체되지 않고 시작 오류가 발생합니다.

3. 첫 실행. 브릿지가 브라우저를 열어 인스턴스의 동의 페이지를 표시합니다(열 수 없는 경우 URL이 stderr에도 출력됩니다). 승인 후 localhost:33380에서 리디렉션을 캡처하고 코드를 토큰으로 교환합니다.

첫 실행은 브라우저에서 승인할 때까지 최대 3분 동안 차단됩니다. MCP 클라이언트가 완료되기 전에 타임아웃되더라도 일반적으로 토큰은 이미 기록되어 있습니다. 다시 연결하면 자동으로 시작됩니다.

토큰 저장. 토큰은 ~/.sn-mcp-bridge/tokens.json(디렉토리 0700, 파일 0600)에 인스턴스 호스트와 클라이언트 ID를 키로 하여 캐시되므로 여러 인스턴스가 하나의 파일에 공존할 수 있습니다. 이후 실행에서는 브라우저 상호작용 없이 캐시된 리프레시 토큰을 재사용합니다. 리프레시 토큰이 만료되면(ServiceNow에서 기본 100일) 브라우저 흐름이 자동으로 다시 트리거됩니다. 파일을 삭제하면 새 인증을 강제할 수 있습니다.

둘 다 함께 사용

OAuth는 REST/Table API만 다룹니다. execute_script, explore_syslog, explore_syslog_transaction, explore_node_logs는 베어러 토큰으로는 제공할 수 없는 폼 로그인 세션이 필요한 ServiceNow UI 엔드포인트(sys.scripts.do, ui_page_process.do)를 호출합니다.

OAuth 변수 와 함께 USERNAME과 PASSWORD를 제공하면 REST 트래픽은 OAuth를 통해 전송되고, 네 가지 도구는 해당 자격 증명을 세션 로그인에 사용합니다. 제공하지 않으면 네 가지 도구는 단순히 등록되지 않으며 어시스턴트가 이를 볼 수 없습니다.

빠른 시작

Claude Code

프로젝트 루트의 .mcp.json에 추가(해당 프로젝트에서만 사용 가능) 또는 ~/.claude/claude_code_config.json에 추가(모든 프로젝트에서 사용 가능):

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com",
				"SN_MYDEV01_USERNAME": "your_username",
				"SN_MYDEV01_PASSWORD": "your_password"
			}
		}
	}
}

OpenAI Codex

프로젝트 루트의 .codex/config.toml에 추가(프로젝트 전용, 신뢰할 수 있는 프로젝트 필요) 또는 ~/.codex/config.toml에 추가(모든 프로젝트에서 사용 가능):

[mcp_servers.sn_mydev01]
command = "npx"
args = ["-y", "sn-mcp-bridge"]

[mcp_servers.sn_mydev01.env]
SN_INSTANCE = "https://mydev01.service-now.com"
SN_MYDEV01_USERNAME = "your_username"
SN_MYDEV01_PASSWORD = "your_password"

VS Code (GitHub Copilot)

프로젝트의 .vscode/mcp.json에 추가:

{
	"servers": {
		"sn_mydev01": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com",
				"SN_MYDEV01_USERNAME": "your_username",
				"SN_MYDEV01_PASSWORD": "your_password"
			}
		}
	}
}

Cursor

프로젝트의 .cursor/mcp.json에 추가:

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com",
				"SN_MYDEV01_USERNAME": "your_username",
				"SN_MYDEV01_PASSWORD": "your_password"
			}
		}
	}
}

OAuth 사용

사용자 이름/비밀번호 쌍을 OAuth 변수로 바꿉니다. 아래 env 블록은 위의 모든 편집기에 적용됩니다. 주변 구성 구문만 다릅니다:

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com",
				"SN_MYDEV01_CLIENT_ID": "your_client_id",
				"SN_MYDEV01_CLIENT_SECRET": "your_client_secret",
				"SN_MYDEV01_GRANT_TYPE": "authorization_code"
			}
		}
	}
}

execute_script 및 진단 도구를 계속 사용하려면 동일한 블록에 SN_MYDEV01_USERNAME 및 SN_MYDEV01_PASSWORD를 추가하세요. 둘 다 함께 사용을 참조하세요.

여러 인스턴스

각 인스턴스에 대해 별도의 서버 항목을 추가합니다. 구성 형식은 위와 동일합니다. 서버 이름과 인스턴스별 자격 증명만 다르게 반복하면 됩니다.

Secretless AI로 자격 증명 보호

Secretless AI는 자격 증명을 안전한 백엔드에 저장하고 secretless-ai run을 통해 런타임에 주입합니다.

아래 예제는 사용자 이름과 비밀번호를 보호하지만, OAuth를 사용하는 경우 SN_MYDEV01_CLIENT_SECRET에도 동일한 접근 방식을 적용할 수 있습니다.

설정

1. 자격 증명 저장:

npx secretless-ai secret set SN_MYDEV01_USERNAME=your_username

# Omit the value so it prompts interactively — keeps the password out of shell history
npx secretless-ai secret set SN_MYDEV01_PASSWORD

2. MCP 구성 업데이트하여 래퍼로 secretless-ai run을 사용합니다. --only 플래그는 주입할 시크릿을 지정합니다. SN_INSTANCE는 시크릿이 아니므로 env 블록에 그대로 둡니다:

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "secretless-ai", "run", "--only", "SN_MYDEV01_USERNAME,SN_MYDEV01_PASSWORD", "--", "npx", "-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com"
			}
		}
	}
}

여러 인스턴스의 경우 패턴을 반복합니다. 각 인스턴스의 자격 증명을 접두사가 붙은 이름으로 저장하고 해당 --only 목록이 있는 서버 항목을 추가합니다:

{
	"mcpServers": {
		"sn_mydev01": {
			"command": "npx",
			"args": ["-y", "secretless-ai", "run", "--only", "SN_MYDEV01_USERNAME,SN_MYDEV01_PASSWORD", "--", "npx", "-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://mydev01.service-now.com"
			}
		},
		"sn_myprod01": {
			"command": "npx",
			"args": ["-y", "secretless-ai", "run", "--only", "SN_MYPROD01_USERNAME,SN_MYPROD01_PASSWORD", "--", "npx", "-y", "sn-mcp-bridge"],
			"env": {
				"SN_INSTANCE": "https://myprod01.service-now.com"
			}
		}
	}
}

다른 편집기의 구성 형식은 Quick Start에 표시된 것과 동일한 패턴을 따릅니다. — command/args를 secretless 래퍼로 교체하면 됩니다.

지원되는 백엔드

대안: protect-mcp

MCP 구성이 전역 구성 경로(예: ~/.vscode/mcp.json, ~/.cursor/mcp.json)에 있는 경우, protect-mcp를 사용하여 한 번에 자동으로 스캔하고 보호할 수 있습니다:

npx secretless-ai protect-mcp --backend keychain

mcp-status 및 mcp-unprotect로 상태를 확인하거나 되돌릴 수 있습니다:

npx secretless-ai mcp-status
npx secretless-ai mcp-unprotect

제한 사항: protect-mcp, mcp-status, mcp-unprotect는 전역 구성 파일만 검색합니다. 프로젝트 디렉터리 내의 .vscode/mcp.json, .mcp.json, .codex/config.toml과 같은 작업 영역 수준 구성은 찾지 않습니다. 작업 영역 구성의 경우 위의 secret set + run 접근 방식을 사용하세요.

Secretless AI에 대한 자세한 내용은 전체 문서를 참조하세요.

요구 사항

• Node.js 18+ (네이티브 fetch 지원)

• REST API 액세스가 가능한 ServiceNow 인스턴스

• 인스턴스에 대한 기본 인증 자격 증명 또는 등록된 OAuth 애플리케이션(인증 참조)

라이선스

MIT