mfa-servicenow-mcp 1.2.2

A Model Context Protocol (MCP) server implementation for ServiceNow

ServiceNow MCP Server

English | 한국어

ServiceNow MCP server with browser-based authentication for MFA/SSO environments. Designed for direct use from MCP clients such as Claude Desktop, Claude Code, OpenCode, Gemini Code Assist, and similar local MCP hosts.

Quick Start

Most users do not need to clone this repository. If you have uv, you can register the server directly in your MCP client.

1. Register in Your MCP Client

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "servicenow": {
      "command": "uvx",
      "args": [
        "mfa-servicenow-mcp",
        "--instance-url", "https://your-instance.service-now.com",
        "--auth-type", "browser",
        "--browser-headless", "false"
      ]
    }
  }
}

OpenCode / Gemini / Vertex AI

{
  "mcp": {
    "servicenow": {
      "type": "local",
      "command": [
        "uvx", "mfa-servicenow-mcp",
        "--instance-url", "https://your-instance.service-now.com",
        "--auth-type", "browser",
        "--browser-headless", "false"
      ],
      "enabled": true
    }
  }
}

2. Run Directly From a Terminal

uvx mfa-servicenow-mcp --instance-url "https://your-instance.service-now.com" --auth-type "browser"

• The first run may install browser dependencies automatically.
• Browser auth may open a login window.
• Use --browser-headless false if you want an interactive MFA/SSO flow.

3. Install as a Local Command

uv tool install mfa-servicenow-mcp
servicenow-mcp --instance-url "https://your-instance.service-now.com" --auth-type "browser"

4. Browser Auth Setup

Browser authentication uses Playwright to drive your local browser for MFA/SSO login. Playwright is an optional dependency — install it separately:

# 1. Install Playwright
pip install playwright
# or
uv pip install playwright

# 2. Install the browser binary (uses your local Chromium)
playwright install chromium

With uvx:

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

Or install as a bundle:

pip install "mfa-servicenow-mcp[browser]"
playwright install chromium

Playwright is only needed for browser auth. Basic, OAuth, and API Key auth work without it.

Windows users can also use WINDOWS_INSTALL.md.

Features

• Browser authentication for MFA/SSO environments
• Safe write confirmation with confirm='approve'
• Payload safety limits and truncation for large records
• Tool packages for standard users, service desk, portal developers, and platform developers
• Developer-focused tools for logs, source lookup, workflow inspection, and update set operations

Authentication

Choose the auth mode based on your ServiceNow environment.

Browser Auth

Use this for Okta, Entra ID, SAML, MFA, or any interactive SSO flow.

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

Optional browser-related flags:

• --browser-username
• --browser-password
• --browser-user-data-dir
• --browser-timeout
• --browser-probe-path

Environment variables:

SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_AUTH_TYPE=browser
SERVICENOW_BROWSER_HEADLESS=false

Basic Auth

Use this for PDIs or instances without MFA.

uvx mfa-servicenow-mcp \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type "basic" \
  --username "your_id" \
  --password "your_password"

OAuth

Current CLI support expects OAuth password grant inputs.

uvx mfa-servicenow-mcp \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type "oauth" \
  --client-id "your_client_id" \
  --client-secret "your_client_secret" \
  --username "your_id" \
  --password "your_password"

If --token-url is omitted, the server defaults to https://<instance>/oauth_token.do.

API Key

uvx mfa-servicenow-mcp \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type "api_key" \
  --api-key "your_api_key"

Default header: X-ServiceNow-API-Key

Tool Packages

Set MCP_TOOL_PACKAGE to choose a smaller tool set. Default: standard

Package	Intended Use	Highlights
standard	General users	Incidents, catalog, knowledge, core queries
portal_developer	Portal developers	Portal code, script includes, safe logs, source lookup, workflow read, update set commit/publish
platform_developer	Platform developers	Script includes, safe logs, source lookup, workflows, UI policy, change set management
service_desk	Operations	Incident handling, comments, user lookup, article lookup
full	Admin / unrestricted	Broad access across all implemented tool domains

Safety Policy

All mutating tools are protected by explicit confirmation.

Rules:

1. Tools such as create_, update_, delete_, execute_, add_, commit_, and publish_ require confirmation.
2. You must pass confirm='approve'.
3. Without that parameter, the server rejects the request before execution.

This policy applies regardless of the selected tool package.

Portal investigation tools are also conservative by default.

• search_portal_regex_matches starts with widget-only scanning, linked expansion off, and small default limits.
• download_portal_sources does not pull linked Script Includes or Angular Providers unless explicitly requested.
• Large portal scans are capped server-side and return warnings when the request is broader than the safe default.
• The intended workflow is: target one widget or a small widget list first, then opt in to broader expansion only when needed.

Example targeted portal search:

{
  "regex": "btnClickLoadData|myQuery",
  "widget_ids": ["jobWFMngt2Wd"],
  "max_widgets": 1,
  "max_matches": 20
}

Example broader search with explicit opt-in:

{
  "regex": "btnClickLoadData|myQuery",
  "widget_ids": ["jobWFMngt2Wd", "jobWFMngtLegacyWd"],
  "include_linked_script_includes": true,
  "include_linked_angular_providers": true,
  "max_widgets": 2,
  "max_matches": 50
}

Developer Setup

If you want to modify the source locally:

git clone https://github.com/jshsakura/mfa-servicenow-mcp.git
cd mfa-servicenow-mcp

uv venv
uv pip install -e ".[browser,dev]"
uv run playwright install chromium

Windows-specific setup: WINDOWS_INSTALL.md

Documentation

• Catalog Guide
• Change Management Guide
• Workflow and Developer Tools
• Korean README

Related Projects and Acknowledgements

• This repository includes tools that were consolidated and refactored from earlier internal / legacy ServiceNow MCP implementations. You can still see that lineage in modules such as core_plus.py and tool_utils.py.
• Some developer productivity workflows, especially server-side source lookup, were designed with ideas inspired by SN Utils. This project does not bundle or redistribute SN Utils code. It implements MCP-oriented server tools separately.
• This project is focused on MCP server use cases rather than browser-extension UX. If you want in-browser productivity features directly inside ServiceNow, SN Utils remains a strong companion tool.

License

MIT License