sn-mcp-bridge

Легковесный Model Context Protocol (MCP) сервер, который предоставляет AI-ассистентам по разработке полную возможность разработки на ServiceNow — без необходимости установки где-либо. Он работает локально через npx и подключается к ServiceNow через Table API.

ServiceNow — это платформа разработки на основе записей. Скрипт-инклуды, бизнес-правила, клиентские скрипты, UI-действия, ACL — каждый артефакт разработки является записью в системной таблице. Здесь нет отдельного «слоя кода»; Table API является API разработки. Это означает, что операции CRUD через этот сервер предназначены не только для запроса данных — это то, как вы создаете:

• insert_record в sys_script_include → создать новый скрипт-инклуд

• update_record на sys_script → изменить бизнес-правило

• query_data на sys_script_client → прочитать все клиентские скрипты для таблицы

• delete_record на sys_ui_action → удалить UI-действие

Для задач, выходящих за рамки CRUD — тестирование логики, выполнение сложных запросов GlideRecord, вызов скрипт-инклудов или многошаговые транзакции — execute_script предоставляет полноценную среду выполнения JavaScript на стороне сервера.

Сервер работает с правами того пользователя, чьи учетные данные вы предоставили — он может читать/записывать только те таблицы и поля, к которым у этого пользователя есть доступ. Инструмент execute_script требует учетных данных администратора, так как он запускает фоновые скрипты через sys.scripts.do.

Аутентификация поддерживает как Basic Auth, так и OAuth 2.0 (авторизационный код) — см. Аутентификация.

В сообществе распространяется множество открытых MCP-серверов ServiceNow. Этот существует, чтобы оставаться простым, чистым и легко улучшаемым — обычный JS без этапа сборки (4 исходных файла, нативный fetch, Node.js 18+), а добавление инструмента — это один вызов server.registerTool().

Инструменты

CRUD

Схема и обнаружение

Аналитика

Расширенные

Диагностика

¹ Для этих четырех инструментов требуется имя пользователя и пароль — см. Аутентификация. Они не регистрируются, если настроены только учетные данные OAuth.

Related MCP server: ServiceNow MCP Server

Аутентификация

Мост поддерживает два режима. Он выбирает OAuth, когда установлены CLIENT_ID, CLIENT_SECRET и GRANT_TYPE; в противном случае используется Basic Auth.

Все переменные следуют одному соглашению об именовании: <INSTANCE_NAME> — это поддомен из SN_INSTANCE, преобразованный в верхний регистр, с заменой дефисов на подчеркивания (например, https://mydev01.service-now.com → SN_MYDEV01_USERNAME). Если переменная с префиксом не установлена, мост переходит к беспрефиксной форме (SN_USERNAME, SN_CLIENT_ID, …).

Basic Auth

Предупреждение: В приведенных ниже примерах используются текстовые учетные данные, чтобы вы могли быстро начать работу. Это означает, что ваш пароль хранится в файле на диске и виден AI-ассистенту в каждом вызове API к LLM-провайдеру. После того как вы убедитесь, что соединение работает, настоятельно рекомендуется следовать инструкциям Защита учетных данных с помощью Secretless AI, чтобы переместить секреты из конфигурации!

OAuth 2.0 (Авторизационный код)

OAuth полностью исключает пароль ServiceNow из конфигурации. Мост авторизуется один раз через ваш браузер, а затем самостоятельно обновляет краткосрочный токен доступа.

1. Зарегистрируйте OAuth-приложение в ServiceNow. Перейдите в Система OAuth → Реестр приложений, нажмите Создать, выберите Создать конечную точку OAuth API для внешних клиентов. Дайте ему имя, установите URL перенаправления на http://localhost:33380/callback и сохраните. Скопируйте сгенерированные ID клиента и Секрет клиента.

2. Настройте мост:

Установка любого из CLIENT_ID / CLIENT_SECRET / GRANT_TYPE без остальных приводит к ошибке при запуске, а не к бесшумному переходу на Basic Auth.

3. Первый запуск. Мост открывает ваш браузер на странице согласия экземпляра (URL также выводится в stderr, если это невозможно). После того как вы подтвердите, он перехватывает перенаправление на localhost:33380 и обменивает код на токены.

Первый запуск блокируется на время до трех минут в ожидании вашего подтверждения в браузере. Если ваш MCP-клиент выйдет из тайм-аута до того, как вы закончите, токены обычно уже записаны — просто переподключитесь, и мост запустится без лишних действий.

Хранение токенов. Токены кэшируются в ~/.sn-mcp-bridge/tokens.json (каталог с правами 0700, файл с правами 0600), ключом служат хост экземпляра и ID клиента, так что несколько экземпляров могут сосуществовать в одном файле. Последующие запуски повторно используют кэшированный токен обновления без взаимодействия с браузером. Когда срок действия токена обновления истекает (100 дней по умолчанию в ServiceNow), поток браузера запускается автоматически. Удалите файл, чтобы принудительно выполнить новую авторизацию.

Использование обоих вместе

OAuth покрывает только REST/Table API. execute_script, explore_syslog, explore_syslog_transaction и explore_node_logs обращаются к UI-конечным точкам ServiceNow (sys.scripts.do, ui_page_process.do), которым требуется сессия, созданная через форму входа, которую bearer-токен предоставить не может.

Если вы укажете USERNAME и PASSWORD наряду с переменными OAuth, 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 вместо Basic Auth

Замените пару имя пользователя/пароль на переменные 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.

В приведенных ниже примерах защищаются имя пользователя и пароль, но тот же подход работает для SN_MYDEV01_CLIENT_SECRET, если вы используете OAuth.

Настройка

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)

• Экземпляр ServiceNow с доступом к REST API

• Либо учетные данные базовой аутентификации для экземпляра, либо зарегистрированное OAuth-приложение (см. Аутентификация)

Лицензия

MIT