ServiceNow MCP

servicenow-mcp-ai — Servidor MCP de ServiceNow

📖 Sitio de documentación →

Un servidor de Model Context Protocol que permite a un cliente MCP (VS Code, Claude Desktop, etc.) ejecutar comandos contra una instancia de ServiceNow a través de sus API REST: Table, Aggregate, Attachment, Import Set, Batch y CMDB, además de las API de plugin de Service Catalog, Change Management y Knowledge. Las credenciales se guardan en un archivo de entorno local y se pueden actualizar en tiempo de ejecución mediante una herramienta.

¿Actualizando desde 1.x? v2.0 hace que las escrituras sean plan-by-default: create/update/delete y las demás herramientas de escritura de registros devuelven una vista previa no mutante a menos que pases apply: true (o establezcas SN_WRITE_MODE=apply para restaurar el comportamiento v1 de "ejecutar inmediatamente"). Consulta el CHANGELOG → 2.0.0 para la nota de migración completa.

Contenidos: Demo rápida · Características · Requisitos · Configuración · Configurar credenciales · Ejecutar / depurar · Desarrollar · Herramientas · Recursos · Prompts · Estructura del proyecto · Notas de seguridad · Documentación del proyecto · Soporte

Construido y mantenido en mi tiempo libre — si te resulta útil, una propina de GitHub Sponsors lo mantiene en marcha. Las opciones completas de Soporte están cerca del final.

Demo rápida

Tres cosas que la plataforma hace difíciles, una llamada cada una. Apunta tu cliente MCP a una instancia (Configuración) y pregunta:

1. "¿Dónde se usa realmente este campo?" — cada script, regla de negocio, script de cliente, UI policy/action y ACL que lo toca, como JSON o un grafo Mermaid. El find usages de nivel IDE que ServiceNow no tiene botón para:

// servicenow_where_used
{
  "kind": "field", // "table" | "field" | "script"
  "name": "u_cost_center",
  "mermaid": true, // also render a reference graph
}

2. "¿Qué se ejecuta cuando guardo este registro?" — la cadena completa de automatización en orden de ejecución (display → before → after → reglas de negocio asíncronas, luego flows, workflows y notificaciones), cada una con su condición — una prueba lógica que ejecuta nada:

// servicenow_trace_table_event
{
  "table": "incident",
  "operation": "update", // insert | update | delete | query
}

3. "¿Qué se desvió entre dev y prod?" — un diff en Markdown de tablas, columnas, scripts (por SHA-256) y plugins entre dos perfiles configurados, con un código de salida compatible con CI para que un pipeline pueda bloquear un despliegue arriesgado:

servicenow-mcp-ai drift dev prod   # report on stdout; exit 1 on drift, 0 if clean

Las tres son de solo lectura y funcionan contra cualquier instancia — incluida una PDI gratuita — con el modelo y el cliente de tu elección.

Características

• API Table completa: consultar, leer, crear, actualizar y eliminar registros en cualquier tabla, con consultas codificadas, selección de campos y paginación.
• API adicionales de ServiceNow: Aggregate (Stats), Attachment (listar/subir/descargar/eliminar), Import Set, Batch (muchas llamadas REST en una sola solicitud), además de metadatos de tablas/columnas (sys_db_object, sys_dictionary).
• API de procesos y plugins: CMDB (CRUD de CI con conocimiento de clases + metadatos vía IRE), Service Catalog (navegar/solicitar artículos), Change Management (creación tipada + detección de conflictos) y Knowledge (búsqueda de artículos). Las API con ámbito de plugin informan claramente cuando no están activas en la instancia.
• Inteligencia de scripts: lee y busca el código propio de la instancia (reglas de negocio, script includes, scripts de cliente, UI policies/actions, trabajos programados, scripts transform/REST, ACLs) y obtén una imagen completa de la automatización de una tabla — todo de solo lectura a través de la API Table.
• Trazado de flujos y verificación de código (Fase 8): traza de forma determinista qué ejecuta una operación de tabla (paquete flows — reglas de negocio, flows, workflows y notificaciones, en orden, con un diagrama de flujo Mermaid), lee flujos de Flow Designer e historial de ejecuciones, y analiza scripts contra un conjunto de reglas local con un informe agregado de salud del código (codecheck). Ejecuta pruebas ATF mediante la API CI/CD (atf, opt-in, no predeterminado — las herramientas de ejecución se ejecutan en la instancia).
• Autodocumentación: una base de conocimiento local en Markdown (leer/escribir/buscar) más generadores Mermaid deterministas (diagramas ER a partir de referencias, diagramas de flujo de ciclo de vida de registros a partir de reglas de negocio) para que el servidor construya contexto duradero y reutilizable.
• Prompts: flujos de trabajo listos para usar (triaje de incidentes, análisis de impacto de cambios, documentar una tabla) que orquestan las herramientas.
• Paquetes de herramientas: carga solo los grupos de herramientas que necesitas mediante SN_TOOL_PACKAGES (perfil predeterminado core; all habilita todo).
• Autenticación Basic u OAuth 2.0 sobre HTTPS; la contraseña/token nunca se devuelve en la respuesta.
• Controles de privilegio mínimo: listas de permitir/denegar tablas y un modo global de solo lectura.
• Resiliencia: tiempo de espera por solicitud, reintento con backoff y Retry-After, protección SSRF y protección de tamaño de resultado.
• Anotaciones de herramientas y recursos MCP, cargas de error estructuradas y registro estructurado en stderr.
• Credenciales en un archivo de entorno (proyecto, ~/.config o SN_ENV_FILE), actualizables en tiempo de ejecución mediante servicenow_set_credentials.

Requisitos

• Node.js 20+ (obligatorio: engines + una protección en tiempo de ejecución con un mensaje claro; el proyecto apunta a la versión en .nvmrc).

Configuración

Desde el código fuente (para desarrollo):

npm install
npm run build

O ejecuta el paquete publicado directamente, sin clonar:

npx servicenow-mcp-ai

Regístralo con un cliente MCP (Claude Desktop, VS Code Chat, el Inspector…) apuntando el comando del servidor a npx:

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

Plugin de Claude Code (configuración cero — instala el servidor ya conectado):

/plugin marketplace add IvanBBaev/servicenow-mcp-ai
/plugin install servicenow-mcp-ai

VS Code — instala la extensión ServiceNow MCP desde el Marketplace (code --install-extension ivanbbaev.servicenow-mcp-ai); registra el servidor en Copilot Chat (modo agente) automáticamente, sin mcp.json manual. Código fuente: extension/.

Las credenciales se leen de ~/.config/servicenow-mcp-ai/.env (o de variables de entorno reales) — consulta a continuación.

Inicio rápido

El camino más rápido son tres líneas de autenticación Basic — establece estas (en el archivo de entorno o en el entorno real) y estarás conectado:

SN_INSTANCE=dev12345.service-now.com
SN_USER=your.username
SN_PASSWORD=your-password

Todo lo demás es ajuste opcional; consulta la referencia completa de Variables de entorno para el resto.

Más allá de una prueba rápida, prefiere OAuth sobre una contraseña almacenada. Para cualquier cosa compartida o de larga duración, ejecuta el npx servicenow-mcp-ai login único en su lugar — almacena un token de actualización, no tu contraseña. Consulta Configurar credenciales → OAuth 2.1.

Verifica tu configuración

Una vez establecidas las tres variables, confirma la conexión antes de empezar:

1. Ejecuta la herramienta servicenow_test_connection — lee un registro de sys_user y reporta ok, estado HTTP y latencia.
2. Ejecuta servicenow_check_capabilities — muestra una vista previa de qué tablas sys_* restringidas a administradores puede leer realmente el usuario conectado.

O haz ambas desde el shell de una sola vez:

npx servicenow-mcp-ai doctor   # checks credentials, reachability and capabilities

Configurar credenciales

Las credenciales viven en .env en la raíz del proyecto (ignorado por git):

SN_INSTANCE=your-instance.service-now.com
SN_USER=your.username@example.com
SN_PASSWORD=your-password

SN_INSTANCE acepta dev12345, dev12345.service-now.com o una URL completa de https://.

También puedes establecerlas o cambiarlas en tiempo de ejecución llamando a la herramienta servicenow_set_credentials — los nuevos valores se escriben directamente de vuelta al archivo de entorno.

El archivo de entorno se resuelve en este orden: SN_ENV_FILE, luego ~/.config/servicenow-mcp-ai/.env (XDG) si está presente, luego .env en la raíz del proyecto. Una instalación global/npx por lo tanto escribe en tu configuración de usuario en lugar de node_modules. Las variables de entorno reales siempre tienen prioridad sobre el archivo.

OAuth 2.1 (Authorization Code + PKCE) — recomendado

Registra un endpoint de API OAuth de Authorization Code en ServiceNow con una URL de redirección de loopback (p. ej. http://localhost:53682/callback), establece SN_OAUTH_CLIENT_ID (y SN_OAUTH_CLIENT_SECRET para un cliente confidencial), y luego ejecuta el inicio de sesión interactivo único:

npx servicenow-mcp-ai login

Abre el navegador, apruebas, y el token de actualización obtenido se almacena en tu archivo de entorno. El servidor entonces se ejecuta de forma no interactiva (concesión refresh_token) — nunca se almacena una contraseña. PKCE (S256) se usa siempre.

La concesión de contraseña (ROPC) de OAuth 2.0 está obsoleta en OAuth 2.1 y deshabilitada en muchas instancias; prefiere login. Las concesiones client_credentials y refresh_token siguen siendo compatibles para cuentas de servicio. Consulta .env.example.

Métodos de autenticación compatibles

Cada método de autenticación REST entrante que ofrece ServiceNow está cubierto:

Método	SN_AUTH	Establecer	Notas
Basic	basic	SN_USER / SN_PASSWORD	Predeterminado.
OAuth 2.1 — Authorization Code + PKCE	oauth	npx servicenow-mcp-ai login	Recomendado. Interactivo, almacena un token de actualización.
OAuth — Client Credentials	oauth	SN_OAUTH_GRANT=client_credentials	Servicio a servicio.
OAuth — Refresh Token	oauth	SN_OAUTH_GRANT=refresh_token + SN_OAUTH_REFRESH_TOKEN	Establecido por login.
OAuth — JWT Bearer	oauth	SN_OAUTH_GRANT=jwt_bearer + SN_OAUTH_JWT_KEY	Aserción RS256; sin contraseña.
OAuth — Password (ROPC)	oauth	SN_OAUTH_GRANT=password	Obsoleto.
API Key	apikey	SN_API_KEY	Cabecera x-sn-apikey.
Bearer token	token	SN_BEARER_TOKEN	Token preobtenido, usado tal cual.
Mutual TLS (certificado de cliente)	none (o en capas)	SN_TLS_CLIENT_CERT / _KEY	El certificado se asigna a un usuario; necesita undici opcional.

Variables de entorno

Todos los ajustes se leen de .env (o del entorno de proceso real, que tiene prioridad). Solo las tres primeras son obligatorias; el resto son ajustes opcionales. Consulta .env.example para una plantilla.

Variable	Requerido	Predeterminado	Descripción
SN_INSTANCE	sí	—	Nombre de instancia, host o URL https:// (dev12345, dev12345.service-now.com).
SN_USER	sí	—	Nombre de usuario de ServiceNow para autenticación Basic.
SN_PASSWORD	sí	—	Contraseña de ServiceNow. Nunca se registra ni se devuelve mediante ninguna herramienta.
SN_TIMEOUT_MS	no	30000	Tiempo de espera por solicitud en milisegundos.
SN_MAX_RETRIES	no	2	Reintentos para fallos transitorios (429/5xx, errores de red). Las escrituras no idempotentes solo se reintentan en errores de conexión.
SN_MAX_RECORDS	no	10000	Límite máximo de registros devueltos por una consulta fetchAll.
SN_MAX_RESULT_CHARS	no	100000	Presupuesto de caracteres para un resultado de consulta antes de que se trunque para el cliente.
SN_ALLOWED_HOSTS	no	—	Lista de permitidos de hosts separada por comas (para dominios personalizados o de nube soberana). Cuando se establece, solo se contactan los hosts que coinciden. Cuando no se establece, solo se permiten instancias *.service-now.com y se bloquean los hosts internos/loopback (protección SSRF).
SN_AUTH	no	auto	Método de autenticación: basic, oauth, apikey, token o none (mTLS solo con certificado). Se auto-detecta a partir de las claves presentes (clave API → bearer → OAuth → Basic).
SN_API_KEY	no	—	Clave API entrante de ServiceNow, enviada como encabezado x-sn-apikey (habilita el modo apikey).
SN_BEARER_TOKEN	no	—	Un token bearer obtenido previamente, enviado tal cual como Authorization: Bearer … (habilita el modo token).
SN_OAUTH_CLIENT_ID	no	—	ID de cliente OAuth (su presencia habilita OAuth).
SN_OAUTH_CLIENT_SECRET	no	—	Secreto de cliente OAuth.
SN_OAUTH_GRANT	no	password	Concesión OAuth: password (obsoleto — ROPC), client_credentials, refresh_token o jwt_bearer. El comando login establece esto a refresh_token por ti.
SN_OAUTH_JWT_KEY	no	—	Clave privada PEM para la concesión jwt_bearer (o SN_OAUTH_JWT_KEY_FILE). Reclamaciones opcionales: SN_OAUTH_JWT_ISS (ID de cliente predeterminado), SN_OAUTH_JWT_SUB (SN_USER predeterminado), SN_OAUTH_JWT_AUD, SN_OAUTH_JWT_KID, SN_OAUTH_JWT_EXP_SEC (predeterminado 300).
SN_OAUTH_REFRESH_TOKEN	no	—	Token de actualización para la concesión refresh_token. Obtenido automáticamente por npx servicenow-mcp-ai login (Código de autorización + PKCE).
SN_OAUTH_REDIRECT_URI	no	http://localhost:53682/callback	URL de redirección de bucle local para el flujo PKCE login. Debe coincidir con la redirección registrada en el endpoint OAuth.
SN_OAUTH_SCOPE	no	—	Alcance OAuth opcional solicitado durante login.
SN_TLS_CLIENT_CERT	no	—	Certificado de cliente (PEM) para mTLS (o SN_TLS_CLIENT_CERT_FILE). Con SN_TLS_CLIENT_KEY presenta un certificado de cliente; el perfil de autenticación mutua de ServiceNow lo mapea a un usuario. Necesita el paquete opcional undici (npm i undici).
SN_TLS_CLIENT_KEY	no	—	Clave privada (PEM) para el certificado de cliente (o SN_TLS_CLIENT_KEY_FILE).
SN_TLS_CA	no	—	Paquete de CA opcional (PEM) para confiar (o SN_TLS_CA_FILE). SN_TLS_REJECT_UNAUTHORIZED=false desactiva la verificación (no recomendado).
SN_TABLES_ALLOW	no	—	Lista de permitidos de tablas separada por comas; cuando se establece, solo estas tablas son accesibles.
SN_TABLES_DENY	no	—	Lista de denegados de tablas separada por comas; siempre gana sobre la lista de permitidos.
SN_READONLY	no	false	Cuando es verdadero, rechaza toda creación/actualización/eliminación.
SN_WRITE_MODE	no	plan	plan (predeterminado) previsualiza una escritura como un diff antes/después sin mutar; apply ejecuta; pasar apply:true fuerza una sola llamada.
SN_REDACT_FIELDS	no	—	DF-5: enmascarar estos valores de campo antes de que los registros lleguen al modelo (separados por comas/espacios).
SN_REDACT_PII	no	false	DF-5: también enmascarar patrones de correo/teléfono/ID nacional dentro de valores de cadena.
SN_TRANSPORT	no	stdio	DF-6: stdio (predeterminado) o http (HTTP Streamable para clientes remotos/agentes).
SN_PORT	no	3000	DF-6: puerto TCP para el transporte http.
SN_HTTP_HOST	no	127.0.0.1	DF-6: dirección de enlace para el transporte http (bucle local por defecto).
SN_HTTP_TOKEN	no	—	DF-6: cuando se establece, las solicitudes http deben enviar Authorization: Bearer <token>.
SN_LOG_LEVEL	no	info	Verbosidad de registro en stderr: error, warn, info, debug.
SN_ENV_FILE	no	—	Ruta explícita al archivo de entorno para leer/escribir.
SN_TOOL_PACKAGES	no	core	Paquetes de herramientas o perfiles separados por comas/espacios para habilitar. Perfiles: core (predeterminado) y all. Paquetes: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf. Las herramientas de administración siempre están activadas. atf ejecuta pruebas en la instancia — habilítalo solo en una instancia que no sea de producción.
SN_PACKAGES_DENY	no	—	Paquetes separados por comas/espacios para excluir incluso si están habilitados por SN_TOOL_PACKAGES. La única forma de bloquear las API de complementos (catálogo, cambio, conocimiento…) — la política de tablas no las ve.
SN_PACKAGES_READONLY	no	—	Paquetes separados por comas/espacios cuyas herramientas de escritura no se registran; sus herramientas de lectura permanecen. Complemento por paquete al SN_READONLY global.
SN_SCHEMA_CACHE_TTL_SEC	no	300	TTL para la caché de lecturas de esquema casi estático (list_tables, describe_table, get_cmdb_meta). 0 desactiva el almacenamiento en caché.
SN_MAX_CONCURRENT	no	4	Máximo de solicitudes HTTP paralelas a la instancia (semáforo simple en proceso).
SN_INCLUDE_REF_LINKS	no	false	Los campos de referencia vuelven sin sus URLs link por defecto (ahorro de tokens). Establezca true para incluirlos.
SN_RESULT_PRETTY	no	false	Los resultados de las herramientas son JSON compacto por defecto (el formato bonito ~duplica los tokens). Establezca true para salida indentada.
SN_DOCS_DIR	no	docs/instance	Directorio en el que el paquete docs lee/escribe Markdown. Las rutas relativas se resuelven contra el directorio de trabajo.
SN_CODESEARCH	no	false	Opte por la API de búsqueda de código (sn_codesearch) para servicenow_search_code (FT-7). Cuando true y el complemento está activo, reemplaza la iteración LIKE; vuelve a LIKE ante cualquier fallo.
SN_PROFILE_<NAME>_*	no	—	Perfiles de conexión con nombre: SN_PROFILE_DEV_INSTANCE / _USER / _PASSWORD definen el perfil dev. Las claves simples SN_INSTANCE/SN_USER/SN_PASSWORD son el perfil default.
SN_ACTIVE_PROFILE	no	default	Qué perfil usan las herramientas. Cambie en tiempo de ejecución con servicenow_use_instance (persistido en el archivo de entorno).

El acceso se controla en dos ejes independientes, porque una restricción de tabla no alcanza a las APIs basadas en plugins (Change, Catalog, Knowledge…). Proteja ambos:

Eje	Habilitar / denegar / solo lectura	Ejemplo
Tablas	SN_TABLES_ALLOW / SN_TABLES_DENY / SN_READONLY	SN_TABLES_DENY=change_request bloquea solo la ruta de la API de Tablas.
Paquetes	SN_TOOL_PACKAGES / SN_PACKAGES_DENY / SN_PACKAGES_READONLY	SN_PACKAGES_DENY=change también bloquea la API de plugin de Gestión de Cambios.

Por lo tanto, denegar la tabla change_request aún deja que la API de Gestión de Cambios (sn_chg_rest) pueda leer/escribir cambios — el eje de paquetes existe por eso. Consulte Notas de seguridad para el modelo completo (incluyendo cómo la API Batch obedece ambos ejes).

Sintaxis de lista: las listas de tablas (SN_TABLES_ALLOW / SN_TABLES_DENY) están separadas por comas; las listas de paquetes (SN_TOOL_PACKAGES, SN_PACKAGES_DENY, SN_PACKAGES_READONLY) aceptan comas o espacios en blanco. Los espacios circundantes se recortan en ambas, y la coincidencia de tablas no distingue mayúsculas — por lo que SN_TABLES_DENY=Change_Request, sys_user funciona.

Ejecutar / depurar

• VS Code: abra la Paleta de Comandos e inicie el servidor definido en .vscode/mcp.json, luego úselo desde Chat.
• MCP Inspector: npm run inspector
• Directamente: npm start

Interfaz de línea de comandos

El binario publicado servicenow-mcp-ai (ejecútelo directamente, o mediante npx servicenow-mcp-ai) tiene tres invocaciones. Todos los ajustes de conexión provienen de variables de entorno / el archivo de entorno (consulte Variables de entorno); solo drift acepta argumentos posicionales.

Comando	Parámetros posicionales	Qué hace	Códigos de salida
servicenow-mcp-ai	(ninguno)	Inicia el servidor MCP. El transporte (stdio por defecto, o http) se elige mediante SN_TRANSPORT; se ejecuta hasta SIGINT/SIGTERM.	0 apagado limpio · 1 error fatal de inicio
servicenow-mcp-ai login	(ninguno — opera sobre el perfil activo)	Inicio de sesión OAuth 2.1 Authorization Code + PKCE de una sola vez: abre el navegador, captura la redirección de loopback, almacena un token de refresco.	0 éxito · 1 fallo de inicio de sesión
servicenow-mcp-ai drift <profileA> <profileB>	<profileA>, <profileB> — dos nombres de perfil configurados	Puerta de deriva de CI DF-3: compara las dos instancias y escribe un informe de diferencias en Markdown.	0 sin deriva · 1 deriva encontrada · 2 uso / error

login opera sobre el perfil activo (SN_ACTIVE_PROFILE, por defecto default) y lee, para ese perfil:

• SN_INSTANCE — obligatorio; la instancia de destino.
• SN_OAUTH_CLIENT_ID — obligatorio; id de cliente de un endpoint OAuth de Authorization Code.
• SN_OAUTH_CLIENT_SECRET — opcional; para un cliente confidencial.
• SN_OAUTH_REDIRECT_URI — opcional; URL de loopback, por defecto http://localhost:53682/callback. Debe coincidir con la redirección registrada en el endpoint.
• SN_OAUTH_SCOPE — opcional; alcance OAuth solicitado.

En caso de éxito, escribe SN_AUTH=oauth, SN_OAUTH_GRANT=refresh_token y SN_OAUTH_REFRESH_TOKEN de vuelta al archivo de entorno (con prefijo de perfil cuando el perfil no es default). La URL de autorización se imprime en stderr en caso de que el navegador no se abra automáticamente.

drift toma dos nombres de perfil posicionales; cada uno debe resolverse a un perfil configurado (SN_PROFILE_<NAME>_*, o las claves simples SN_INSTANCE / SN_USER / SN_PASSWORD para default). El informe Markdown se escribe en stdout (captúrelo como artefacto de CI); un resumen de deriva de una línea va a stderr.

Puerta de deriva de CI (DF-3)

Compare dos perfiles configurados y haga fallar un pipeline ante deriva de configuración:

servicenow-mcp-ai drift dev prod   # report on stdout; exit 1 on drift, 0 if clean, 2 on error

Desarrollo

npm run check     # full gate: build, lint, format check, coverage-gated tests, prod audit
npm test          # unit tests only (node:test; needs a prior npm run build)
npm run lint      # ESLint (flat config + typescript-eslint)
npm run format    # format with Prettier

Consulte CONTRIBUTING.md para las convenciones (un commit por tarea, las pruebas acompañan al cambio, documentación generada).

Herramientas

Esta tabla se genera a partir de los registros de herramientas — edite las definiciones de herramientas en src/tools/, luego ejecute npm run docs:readme.

Package	Tool	Read-only	Description
table	servicenow_query_table	yes	Lee registros de cualquier tabla de ServiceNow mediante la Table API
table	servicenow_get_record	yes	Lee un único registro de una tabla por su sys_id
table	servicenow_create_record	no	Crea un nuevo registro en una tabla con los valores de campo proporcionados
table	servicenow_update_record	no	Actualiza campos de un registro existente identificado por su sys_id
table	servicenow_delete_record	no	Elimina un registro de una tabla por su sys_id
schema	servicenow_list_tables	yes	Lista tablas de sys_db_object, opcionalmente filtradas por un fragmento de nombre o etiqueta
schema	servicenow_describe_table	yes	Lista las columnas de una tabla (nombre, etiqueta, tipo, obligatorio, referencia) desde sys_dictionary
aggregate	servicenow_aggregate	yes	Calcula agregados del lado del servidor (count, avg, min, max, sum) sobre una tabla mediante la Stats API, con agrupación opcional…
attachment	servicenow_list_attachments	yes	Lista metadatos de adjuntos, opcionalmente limitados a un registro específico (tabla + sys_id)
attachment	servicenow_get_attachment	yes	Lee los metadatos de un único adjunto por su sys_id
attachment	servicenow_download_attachment	yes	Descarga los bytes de un adjunto, devueltos como base64
attachment	servicenow_upload_attachment	no	Adjunta un archivo (proporcionado como base64) a un registro identificado por tabla + sys_id
attachment	servicenow_delete_attachment	no	Elimina un adjunto por su sys_id
importset	servicenow_insert_import_set_row	no	Inserta una sola fila en una tabla de staging y ejecuta su transform map
importset	servicenow_get_import_set_row	yes	Lee el resultado de la transformación de una fila de staging previamente insertada por su sys_id
batch	servicenow_batch	no	Ejecuta varias sub-solicitudes REST de ServiceNow en un único round-trip HTTP mediante la Batch API
catalog	servicenow_list_catalogs	yes	Lista los Service Catalogs disponibles en la instancia (Service Catalog API)
catalog	servicenow_list_catalog_categories	yes	Lista las categorías dentro de un catálogo de servicios
catalog	servicenow_list_catalog_items	yes	Busca/lista artículos de catálogo ordenables, opcionalmente por texto o categoría
catalog	servicenow_get_catalog_item	yes	Obtiene un artículo de catálogo, incluidos sus variables de pedido, por sys_id
catalog	servicenow_order_catalog_item	no	Ordena un artículo de catálogo directamente ('order now')
change	servicenow_list_changes	yes	Lista solicitudes de cambio mediante la Change Management API
change	servicenow_get_change	yes	Obtiene una única solicitud de cambio por sys_id
change	servicenow_create_change	no	Crea un cambio normal, estándar o de emergencia
change	servicenow_update_change	no	Actualiza campos de una solicitud de cambio por sys_id
change	servicenow_change_conflicts	no	Lee conflictos de agenda para un cambio, o los recalcula (calculate=true)
knowledge	servicenow_search_knowledge	yes	Búsqueda de texto completo de artículos de conocimiento (Knowledge API), con encoded query y paginación opcionales
knowledge	servicenow_get_knowledge_article	yes	Obtiene un artículo de conocimiento (contenido y metadatos) por sys_id
knowledge	servicenow_knowledge_highlights	yes	Lista artículos de conocimiento destacados o más vistos para el usuario actual
cmdb	servicenow_list_cis	yes	Lista elementos de configuración de una clase CMDB mediante la class-aware CMDB Instance API
cmdb	servicenow_get_ci	yes	Obtiene un CI con sus atributos y relaciones entrantes/salientes por clase y sys_id
cmdb	servicenow_create_ci	no	Crea un CI mediante la CMDB Instance API (enrutado a través de Identification & Reconciliation)
cmdb	servicenow_update_ci	no	Actualiza los atributos de un CI mediante la CMDB Instance API (IRE)
cmdb	servicenow_get_cmdb_meta	yes	Obtiene el esquema/metadatos de una clase CMDB (atributos, reglas de relación) desde la CMDB Meta API
scripts	servicenow_list_scripts	yes	Lista artefactos de script de un tipo como metadatos compactos (sin código fuente)
scripts	servicenow_get_script	yes	Lee un artefacto de script completo, incluidos su código fuente y su contexto de ejecución
scripts	servicenow_search_code	yes	Busca una subcadena literal en el código fuente del script en uno o todos los tipos de script
scripts	servicenow_table_logic	yes	Ensambla la automatización que se ejecuta en una tabla: business rules (ordenadas por when+order), client scripts, UI po…
scripts	servicenow_where_used	yes	Encuentra dónde se referencia una tabla, campo o script en el código de la instancia: referencias textuales en cada s…
flows	servicenow_trace_table_event	yes	Traza de forma determinista lo que ServiceNow ejecutaría para una operación de tabla, en orden de ejecución: display/before…
flows	servicenow_list_flows	yes	Lista flujos de Flow Designer (sys_hub_flow) o workflows heredados (kind: 'workflow') como metadatos compactos
flows	servicenow_get_flow	yes	Obtiene una vista estructurada de un flujo o workflow: su trigger (tabla/condición/cuándo) y sus pasos ordenados
flows	servicenow_get_flow_runs	yes	Lee evidencia de ejecución de flujos desde sys_flow_context — por sys_id del flujo o por el registro (document) contra el que se ejecutó…
codecheck	servicenow_lint_script	yes	Ejecuta reglas deterministas de calidad de código sobre un artefacto de script (sys_ids/URLs hard-coded, bucles ilimitados o en-loo…
codecheck	servicenow_lint_table	yes	Lint de cada business rule activa, client script y UI policy de una tabla (vía table_logic), devolviendo por-sc…
codecheck	servicenow_code_health	no	Agrega una imagen de salud del código: recuentos de scripts por tipo, un escáner de seguridad de la capa de control de acceso (ACL scri…
docs	servicenow_docs_list	yes	Lista los documentos Markdown en la carpeta local de documentación de la instancia (SN_DOCS_DIR)
docs	servicenow_docs_read	yes	Lee un documento Markdown de la carpeta local de documentación de la instancia
docs	servicenow_docs_search	yes	Busca una subcadena en la documentación local de la instancia; devuelve un fragmento por coincidencia
docs	servicenow_docs_write	no	Crea o sobrescribe un documento Markdown en la carpeta local de docs y actualiza index.md
docs	servicenow_generate_er_diagram	yes	Construye un diagrama erDiagram de Mermaid desde sys_dictionary: una entidad por tabla más una relación por cada reference…
docs	servicenow_generate_table_flow	yes	Construye un diagrama de flujo Mermaid del ciclo de vida de un registro en una tabla, agrupando business rules activas por fase (disp…
instance	servicenow_snapshot_instance	no	Descarga los metadatos estructurales de la instancia en la carpeta local de docs (SN_DOCS_DIR//): tables.md+…
instance	servicenow_compare_instances	no	Compara dos perfiles de conexión: tablas presentes solo en uno, columnas comunes cuyo tipo/obligatorio/referencia dif…
email	servicenow_send_email	no	Envía un correo electrónico mediante la Email API de la instancia, opcionalmente asociado a un registro (tabla + sys_id)
email	servicenow_get_email	yes	Lee un registro de correo enviado/recibido por su sys_id (Email API)
atf	servicenow_list_atf_tests	yes	Lista pruebas de Automated Test Framework (sys_atf_test) como metadatos: nombre, flag activo, descripción
atf	servicenow_list_atf_suites	yes	Lista suites de pruebas de Automated Test Framework (sys_atf_test_suite) como metadatos
atf	servicenow_run_atf_test	no	Ejecuta una única prueba ATF mediante la CI/CD API
atf	servicenow_run_atf_suite	no	Ejecuta una suite de pruebas ATF mediante la CI/CD API
atf	servicenow_get_atf_result	yes	Consulta una ejecución ATF por su id de ejecución: estado, porcentaje completado y mensaje (CI/CD progress API)
admin	servicenow_set_credentials	no	Guarda o actualiza las credenciales de conexión de ServiceNow
admin	servicenow_list_instances	yes	Lista los perfiles de conexión de ServiceNow configurados (instancias): nombre, host, usuario, flag de solo lectura y si…
admin	servicenow_use_instance	no	Cambia el perfil de conexión de ServiceNow activo (persistido en el archivo de entorno)
admin	servicenow_get_status	yes	Muestra la instancia configurada, el usuario, el modo de autenticación y la política de acceso, y si las credenciales están completas
admin	servicenow_test_connection	yes	Verifica que las credenciales configuradas realmente funcionan: lee un registro de sys_user e informa ok/estado/latencia
admin	servicenow_check_capabilities	yes	Preflight de qué tablas sys_* restringidas por administrador puede leer realmente el usuario conectado, e informa cuáles super…

Todas las herramientas llevan anotaciones MCP (readOnlyHint, destructiveHint, idempotentHint) para que los clientes puedan aplicar la UX de confirmación adecuada.

Paquetes de herramientas

Las herramientas se agrupan en paquetes para que pueda exponer solo lo que un cliente concreto necesita (menos herramientas mantienen al modelo centrado). Configure SN_TOOL_PACKAGES como una lista separada por comas/espacios de perfiles o nombres de paquetes:

• core (por defecto) — table, schema, aggregate, attachment.
• all — todos los paquetes siguientes.
• Paquetes individuales: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf.

Las herramientas de administración (servicenow_set_credentials, servicenow_get_status) están siempre registradas, independientemente de los paquetes activos. Los nombres desconocidos se ignoran. servicenow_get_status informa el enabledPackages resuelto.

# Only table + batch tools (plus the always-on admin tools)
SN_TOOL_PACKAGES=table,batch

Presets

Si prefiere no seleccionar la lista usted mismo, tres presets con nombre cubren los roles habituales. Las herramientas de administración siempre están activas, por lo que no se listan. Cada preset también tiene un alias de una palabra — SN_TOOL_PACKAGES=reader|developer|admin — que se expande al mismo conjunto de paquetes.

Preset	SN_TOOL_PACKAGES=…	Para quién
reader	table,schema,aggregate	Primer contacto, analistas, un juego con PDI — solo lectura y consulta.
developer	table,schema,aggregate,scripts,flows,codecheck,docs	El segmento principal: inteligencia de scripts, trazado de flujos, linting, docs y diagramas.
admin	all	Todo, incluidos el plugin y los paquetes con mucha escritura.

El preset developer se basa en el conjunto reader; el paquete docs incluye los generadores de diagramas Mermaid. Use el alias por brevedad o escriba los paquetes completos para añadir o quitar uno.

Ejemplos

Consulte los 5 incidentes activos más recientes:

// servicenow_query_table
{
  "table": "incident",
  "query": "active=true^ORDERBYDESCsys_created_on",
  "fields": ["number", "short_description", "priority", "state"],
  "limit": 5,
}

Cree un incidente:

// servicenow_create_record
{
  "table": "incident",
  "fields": {
    "short_description": "Printer on 3rd floor is down",
    "urgency": "2",
    "impact": "2",
  },
}

Actualice las credenciales en tiempo de ejecución:

// servicenow_set_credentials
{
  "instance": "dev98765.service-now.com",
  "user": "admin",
  "password": "••••••",
}

Recursos

Los metadatos de solo lectura también se exponen como recursos MCP, para que los clientes puedan adjuntarlos de forma declarativa en lugar de llamar a una herramienta:

URI	Descripción
servicenow://status	Estado de la conexión, modo de autenticación, política de acceso.
servicenow://tables	Lista de tablas de sys_db_object.
servicenow://schema/{table}	Columnas de una tabla de sys_dictionary.
servicenow://docs/{path}	Un documento Markdown del almacén local de docs.

Prompts

Los flujos de trabajo listos para usar se exponen como prompts MCP; orquestan las herramientas e insisten en leer valores reales de la instancia:

Prompt	Argumento	Propósito
servicenow_incident_triage	incident	Resumir, evaluar la prioridad, categorizar y recomendar los siguientes pasos.
servicenow_change_impact_analysis	change	CIs afectados, conflictos de agenda y una decisión go/no-go.
servicenow_document_table	table	Esquema + automatización + diagramas → documento Markdown guardado.

Estructura del proyecto

.
├── .env                   # credentials (git-ignored; or ~/.config/servicenow-mcp-ai/.env)
├── .env.example           # template
├── .github/workflows/     # CI: build + lint + test
├── .vscode/mcp.json       # VS Code MCP server registration
├── eslint.config.js       # ESLint flat config
├── .prettierrc.json       # Prettier config
├── src/
│   ├── index.ts           # bootstrap: load env, register, connect stdio
│   ├── registry.ts        # registers all tool groups
│   ├── resources.ts       # MCP resources (status, tables, schema, docs)
│   ├── prompts.ts         # MCP prompts (triage, change impact, document table)
│   ├── http.ts            # shared REST client (auth, retry, SSRF)
│   ├── auth.ts            # Basic + OAuth 2.0 providers
│   ├── host.ts            # host resolution + SSRF guard
│   ├── policy.ts          # table allow/deny + read-only guards
│   ├── settings.ts        # numeric env settings
│   ├── logging.ts         # structured stderr logger
│   ├── result.ts          # tool results + structured errors
│   ├── servicenow.ts      # Table API client
│   ├── config.ts          # env file read/write + location
│   ├── api/               # aggregate, attachment, import set, batch, catalog, change, knowledge, cmdb, scripts, diagrams, docs, meta
│   └── tools/             # tool registration per API group
├── test/                  # node:test unit + mock-fetch tests
└── build/                 # compiled output (after npm run build)

Nota sobre los nombres: el paquete npm y el repositorio de GitHub son ambos servicenow-mcp-ai (el servicenow-mcp sin ámbito ya estaba ocupado en npm); la carpeta de trabajo local es servicenow-mcp. La diferencia es cosmética y no afecta a la compilación ni al tiempo de ejecución.

Notas de seguridad

• El archivo de entorno está en git-ignore — no confirmes credenciales reales.
• El archivo de entorno se escribe solo con permisos de propietario (0600) — contiene una contraseña en texto plano.
• El servidor usa el transporte stdio y solo registra en stderr; los secretos y las consultas codificadas sin procesar nunca se registran.
• La contraseña/token nunca es devuelto por ninguna herramienta.
• Los hosts están restringidos: sin SN_ALLOWED_HOSTS, solo se contactan instancias *.service-now.com (interno/loopback siempre bloqueado), por lo que un host redirigido o mal escrito no puede recibir credenciales silenciosamente. Establece SN_ALLOWED_HOSTS para optar por un dominio personalizado o de nube soberana.
• Prefiere OAuth 2.0 sobre Basic cuando sea posible (SN_OAUTH_CLIENT_ID).
• Aplica el mínimo privilegio con SN_TABLES_ALLOW / SN_TABLES_DENY y SN_READONLY=true para implementaciones de solo lectura.
• La política de tablas no cubre las API de plugins. SN_TABLES_DENY=change_request bloquea la ruta de la API de Tablas, pero la API de Gestión de Cambios (sn_chg_rest) puede seguir leyendo/escribiendo cambios. Para restringir las superficies respaldadas por plugins, usa SN_PACKAGES_DENY (elimina el paquete completo) o SN_PACKAGES_READONLY (registra solo sus herramientas de lectura). La API Batch también obedece ambos ejes: una sub-solicitud a la ruta de un paquete denegado es rechazada, y las escrituras en un paquete de solo lectura están bloqueadas — un lote no puede usarse para evadir la política de paquetes.

Documentación del proyecto

Documento	Contenido
ARCHITECTURE.md	Arquitectura en capas, diagramas Mermaid (módulos, ciclo de vida de solicitudes, modelo de seguridad, autenticación, paquetes), ADRs condensados
PRODUCT-STATE.md	Estado actual del producto: mapa de cobertura de API, estado de calidad, línea de tiempo histórica, hoja de ruta
ROADMAP.md	Plan a futuro: lanzar 1.0.0, Fase 8 (pruebas de flujo + análisis de código), Fase 9 (diferenciadores competitivos), elementos opcionales y diferidos
COMPETITIVE-ANALYSIS.md	Posicionamiento frente a la consola oficial del Servidor MCP de ServiceNow: comparación, dónde queda estructuralmente rezagado, el plan de impulso de la Fase 9 y riesgos de plataforma
IMPLEMENTATION-PLAN.md	Especificaciones detalladas para las próximas fases (harness 2.0, multi-instancia, pruebas de flujo)
DONE.md / TODO.md	Trabajo completado con referencias de commits / decisiones pendientes
WORKLOG.md / CHANGELOG.md	Diario de trabajo detallado / registro de cambios orientado al usuario
CONTRIBUTING.md / SECURITY.md	Configuración de desarrollo, compuertas y convenciones / modelo de seguridad y reporte

Soporte

Este proyecto se construye y mantiene en mi tiempo libre. Si te ahorra tiempo a ti o a tu equipo, considera apoyar su desarrollo continuo — el patrocinio financia directamente nuevas herramientas, correcciones de errores y el mantenimiento al ritmo de la superficie REST de ServiceNow.

• GitHub Sponsors — único o recurrente, sin que se cobre ninguna tarifa de plataforma (la opción preferida).
• Ko-fi — soporte único rápido; también acepta PayPal, por lo que es la alternativa para quienes no tienen cuenta de GitHub.
• Donar (Donatree) — una página de donación sin cuenta (tarjeta, PayPal y más) para una propina única.

Marca comercial

servicenow-mcp-ai es un proyecto independiente, construido por la comunidad. No está afiliado con, respaldado por, ni patrocinado por ServiceNow, Inc.

"ServiceNow", el logotipo de ServiceNow, "Now" y las marcas relacionadas son marcas comerciales o marcas comerciales registradas de ServiceNow, Inc. en los Estados Unidos y otros países. Se usan en el nombre y la documentación de este proyecto solo de forma nominativa — para identificar la plataforma con la que este software interoperá — y no se implica afiliación ni respaldo. Todos los demás nombres de productos y marcas son propiedad de sus respectivos dueños.

Este proyecto está licenciado bajo la Licencia MIT; esa licencia cubre el código fuente y no otorga ningún derecho a usar las marcas comerciales de ServiceNow.