sn-mcp-bridge

Un servidor ligero del Model Context Protocol (MCP) que otorga a los asistentes de codificación con IA capacidades completas de desarrollo en ServiceNow — sin necesidad de instalación en ningún lugar. Se ejecuta localmente a través de npx y se conecta a ServiceNow mediante la Table API.

ServiceNow es una plataforma de desarrollo basada en registros. Script includes, reglas de negocio, scripts de cliente, acciones de UI, ACLs — cada artefacto de desarrollo es un registro en una tabla del sistema. No existe una "capa de código" separada; la Table API es la API de desarrollo. Eso significa que las operaciones CRUD a través de este servidor no son solo para consultar datos — son la forma en que construyes:

• insert_record en sys_script_include → crear un nuevo script include

• update_record en sys_script → modificar una regla de negocio

• query_data en sys_script_client → leer todos los scripts de cliente para una tabla

• delete_record en sys_ui_action → eliminar una acción de UI

Para tareas que van más allá de CRUD — probar lógica, ejecutar consultas complejas de GlideRecord, llamar a script includes o transacciones de varios pasos — execute_script proporciona un runtime completo de JavaScript del lado del servidor.

El servidor se ejecuta con los permisos del usuario cuyas credenciales proporciones — solo puede leer/escribir las tablas y campos a los que ese usuario tenga acceso. La herramienta execute_script requiere credenciales de administrador, ya que ejecuta scripts en segundo plano a través de sys.scripts.do.

La autenticación soporta tanto Autenticación Básica como OAuth 2.0 (código de autorización) — ver Autenticación.

Existen muchos servidores MCP de ServiceNow de código abierto compartidos en la comunidad. Este existe para mantenerse simple, puro y fácil de mejorar — JS plano sin paso de compilación (4 archivos fuente, fetch nativo, Node.js 18+), y agregar una herramienta es una llamada a server.registerTool().

Herramientas

CRUD

Esquema y Descubrimiento

Analítica

Avanzadas

Diagnóstico

¹ Estas cuatro herramientas requieren un nombre de usuario y contraseña — ver Autenticación. No se registran cuando solo se configuran credenciales OAuth.

Related MCP server: ServiceNow MCP Server

Autenticación

El puente admite dos modos. Usa OAuth cuando se definen CLIENT_ID, CLIENT_SECRET y GRANT_TYPE; de lo contrario, usa Autenticación Básica.

Todas las variables siguen la misma convención de nomenclatura: <NOMBRE_INSTANCIA> es el subdominio de SN_INSTANCE, en mayúsculas y con guiones reemplazados por guiones bajos (por ejemplo, https://mydev01.service-now.com → SN_MYDEV01_USERNAME). Si una variable con prefijo no está definida, el puente recurre a la forma sin prefijo (SN_USERNAME, SN_CLIENT_ID, …).

Autenticación Básica

Advertencia: Los ejemplos a continuación usan credenciales en texto plano para que puedas empezar rápidamente. Esto significa que tu contraseña se almacena en un archivo en disco y es visible para el asistente de IA en cada llamada API al proveedor de LLM. Una vez que hayas confirmado que la conexión funciona, se recomienda encarecidamente que sigas las instrucciones de Asegurar Credenciales con Secretless AI para mover los secretos en texto plano fuera de tu configuración.

OAuth 2.0 (Código de Autorización)

OAuth mantiene tu contraseña de ServiceNow completamente fuera de la configuración. El puente autoriza una vez a través de tu navegador y luego renueva automáticamente un token de acceso de corta duración.

1. Registrar una aplicación OAuth en ServiceNow. Ve a System OAuth → Application Registry, haz clic en New y elige Create an OAuth API endpoint for external clients. Dale un nombre, establece la Redirect URL en http://localhost:33380/callback y guarda. Copia el Client ID y Client Secret generados.

2. Configurar el puente:

Establecer cualquiera de CLIENT_ID / CLIENT_SECRET / GRANT_TYPE sin los demás es un error de inicio en lugar de una recurrencia silenciosa a la Autenticación Básica.

3. Primera ejecución. El puente abre tu navegador en la página de consentimiento de la instancia (la URL también se imprime en stderr si no puede). Después de que apruebes, captura la redirección en localhost:33380 e intercambia el código por tokens.

La primera ejecución se bloquea hasta tres minutos esperando que apruebes en el navegador. Si tu cliente MCP se agota antes de que termines, los tokens normalmente ya se han escrito — solo reconéctate y comenzará silenciosamente.

Almacenamiento de tokens. Los tokens se almacenan en caché en ~/.sn-mcp-bridge/tokens.json (directorio 0700, archivo 0600), indexados por host de instancia y client ID, por lo que múltiples instancias coexisten en un solo archivo. Las ejecuciones posteriores reutilizan el token de actualización almacenado en caché sin interacción con el navegador. Cuando el token de actualización expira (100 días por defecto en ServiceNow), el flujo del navegador se activa automáticamente. Elimina el archivo para forzar una nueva autorización.

Usar ambos juntos

OAuth solo cubre la API REST/Table. execute_script, explore_syslog, explore_syslog_transaction y explore_node_logs acceden a endpoints de UI de ServiceNow (sys.scripts.do, ui_page_process.do) que necesitan una sesión de inicio de sesión de formulario, que un token de portador no puede proporcionar.

Si proporcionas USERNAME y PASSWORD junto con las variables OAuth, el tráfico REST va por OAuth y esas cuatro herramientas usan las credenciales para su inicio de sesión de sesión. Si no lo haces, las cuatro herramientas simplemente no se registran — el asistente nunca las ve.

Inicio Rápido

Claude Code

Agrega a .mcp.json en la raíz de tu proyecto (solo disponible en ese proyecto) o en ~/.claude/claude_code_config.json (disponible en todos los proyectos):

{
	"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

Agrega a .codex/config.toml en la raíz de tu proyecto (solo proyecto, requiere un proyecto de confianza) o en ~/.codex/config.toml (disponible en todos los proyectos):

[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)

Agrega a .vscode/mcp.json en tu proyecto:

{
	"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

Agrega a .cursor/mcp.json en tu proyecto:

{
	"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"
			}
		}
	}
}

Usar OAuth en su lugar

Intercambia el par nombre de usuario/contraseña por las variables OAuth. El bloque env a continuación se aplica a cada editor anterior — solo la sintaxis de configuración circundante difiere:

{
	"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"
			}
		}
	}
}

Para mantener disponibles execute_script y las herramientas de diagnóstico, agrega SN_MYDEV01_USERNAME y SN_MYDEV01_PASSWORD al mismo bloque — ver Usar ambos juntos.

Múltiples Instancias

Agrega una entrada de servidor separada para cada instancia. El formato de configuración es el mismo que el anterior — solo repite el patrón con un nombre de servidor diferente y credenciales específicas de la instancia.

Asegurar Credenciales con Secretless AI

Secretless AI almacena tus credenciales en un backend seguro y las inyecta en tiempo de ejecución mediante secretless-ai run.

Los siguientes ejemplos protegen un nombre de usuario y contraseña, pero el mismo enfoque funciona para SN_MYDEV01_CLIENT_SECRET si estás usando OAuth.

Configuración

1. Almacena tus credenciales:

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. Actualiza tu configuración de MCP para usar secretless-ai run como envoltorio. La bandera --only le indica qué secretos inyectar. SN_INSTANCE no es un secreto y permanece en el bloque 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"
			}
		}
	}
}

Para múltiples instancias, repite el patrón — almacena las credenciales de cada instancia bajo sus nombres con prefijo y agrega una entrada de servidor con la lista --only correspondiente:

{
	"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"
			}
		}
	}
}

El formato de configuración para otros editores sigue el mismo patrón que se muestra en Inicio rápido — solo reemplaza command/args con el envoltorio sin secretos.

Backends compatibles

Alternativa: protect-mcp

Si tus configuraciones de MCP están en rutas de configuración globales (por ejemplo, ~/.vscode/mcp.json, ~/.cursor/mcp.json), puedes usar protect-mcp para escanearlas y asegurarlas automáticamente de una sola vez:

npx secretless-ai protect-mcp --backend keychain

Puedes verificar el estado o revertir con mcp-status y mcp-unprotect:

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

Limitación: protect-mcp, mcp-status y mcp-unprotect solo descubren archivos de configuración globales. No encuentran configuraciones a nivel de espacio de trabajo como .vscode/mcp.json, .mcp.json o .codex/config.toml dentro de directorios de proyecto. Para configuraciones de espacio de trabajo, usa el enfoque de secret set + run anterior.

Para más detalles sobre Secretless AI, consulta la documentación completa.

Requisitos

• Node.js 18+ (para fetch nativo)

• Una instancia de ServiceNow con acceso a la API REST

• Credenciales de autenticación básica para la instancia, o una aplicación OAuth registrada (consulta Autenticación)

Licencia

MIT