ServiceNow MCP Reports

Servidor MCP local que expone dos informes de ServiceNow bajo demanda, construido a partir del plan en [[ServiceNow MCP Server — Syslog & Dev Work Reports (Plan)]]. La narrativa de configuración y la resolución de problemas también están en la bóveda: [[ServiceNow MCP Server — Syslog & Dev Work Reports (Setup Guide)]].

Para ideas sobre cómo extender esto más allá de las dos herramientas actuales, consulta echelon-ai-labs/servicenow-mcp — un servidor ServiceNow Python/FastMCP mucho más grande (incidencias, cambios, catálogo, base de conocimiento, script includes, herramientas Agile). Ya se ha tomado de él: un transporte HTTP accesible de forma remota junto con stdio (paso 7) — ese repositorio expone tanto stdio como SSE; y sus filtros por rango de fechas usan las palabras clave de fechas relativas propias de ServiceNow (ONLast week@javascript:gs.beginningOfLastWeek()@javascript:gs.endOfLastWeek()) en lugar de construir literales de fecha y hora a mano — comparar ese patrón con la consulta de este proyecto es lo que sacó a la luz el bug de zona horaria corregido en el paso 4/Resolución de problemas más abajo. Aún no tomado: su AuthManager, que soporta Basic/OAuth/API-key tras una única interfaz (este proyecto es solo Basic).

Herramientas

Ambas son consultas GET de solo lectura contra la Table API — ninguna herramienta escribe nunca en la instancia. Ambas devuelven únicamente filas crudas/agrupadas; el análisis (sugerencias de corrección, problemas señalados) ocurre en conversación con Claude, no dentro de la herramienta. Ambas paginan automáticamente (queryTableAll en servicenow-client.ts, 1000 filas/página, tope de seguridad de 10 000 filas) en lugar de un sysparm_limit de una sola página hardcodeado — si una consulta alcanza el tope, la respuesta comienza con un bloque de texto explícito ⚠ Truncated antes del JSON, en lugar de devolver silenciosamente un informe parcial. Registradas para ambos puntos de entrada desde el mismo src/create-server.ts.

get_syslog_report

Obtiene las filas de syslog de un solo día, filtradas a warning/error por defecto.

Devuelve un array JSON de:

{
  "sys_created_on": "2026-08-25 17:30:24",
  "message": "SG-Azure Request failed with statusCode: 403 Code: AccessDenied ...",
  "source": "sn_sg_azure_integ",
  "level": "2",
  "node": "..."
}

get_developer_work_report

Obtiene los cambios de sys_update_xml entre dos fechas, agrupados por autor y update set.

Devuelve un array JSON de:

{
  "author": "system",
  "updateSet": "Default",
  "isDefaultUpdateSet": true,
  "changeCount": 2,
  "changes": [
    { "name": "...", "type": "Service Graph Connections State", "created": "2026-08-25 10:30:30" }
  ]
}

Related MCP server: ServiceNow MCP Server

1. Aprovisionar una cuenta de servicio de ServiceNow de solo lectura (manual, una sola vez)

Hazlo en el PDI (https://dev203275.service-now.com), con sesión iniciada como admin:

1. User Administration → Users → New

   • User ID: claude_mcp_readonly

   • Establece una contraseña, desmarca "Password needs reset"

   • Marca "Web service access only" — obligatorio. Sin ello, SNCRestrictBasicAuthUserAuthenticationGate de ServiceNow bloquea la autenticación Basic por REST para esta cuenta incluso con una contraseña correcta, porque la cuenta también tiene permitido el inicio de sesión interactivo en la UI. Síntoma si se omite: cada llamada REST devuelve 401 con "User is not authenticated" mientras que iniciar sesión en la UI con las mismas credenciales funciona bien. Consulta Resolución de problemas.

2. En ese registro de usuario → lista relacionada Roles → Edit → añade:

   • rest_api_explorer (acceso a la API REST)

   • Acceso de lectura a syslog y sys_update_xml/sys_update_set — en un PDI, snc_read_only o el rol itil integrado normalmente cubren esto; confirma que el usuario realmente puede leer esas tablas (consulta el paso 3 más abajo) en lugar de asumir el nombre del rol.

   • No concedas admin — esta cuenta solo debe consultar, según el plan original.

3. Copia .env.example a .env y rellena SN_USER / SN_PASS con esta nueva cuenta.

2. Compilar

cd C:\Users\willr\projects\servicenow-mcp-reports
npm install
npm run build

3. Verificar las credenciales antes de conectarlas a un cliente

$env:SN_INSTANCE="https://dev203275.service-now.com"; $env:SN_USER="claude_mcp_readonly"; $env:SN_PASS="<password>"
node -e "fetch(process.env.SN_INSTANCE+'/api/now/table/sys_user?sysparm_limit=1',{headers:{Authorization:'Basic '+Buffer.from(process.env.SN_USER+':'+process.env.SN_PASS).toString('base64')}}).then(r=>console.log(r.status))"

Debería imprimir 200. Si devuelve 401, comprueba la contraseña; si devuelve 403, el rol aún no cubre esa tabla.

4. Nombre de la tabla syslog, valores de level y filtrado por fecha (resuelto)

Confirmado en esta instancia el 2026-08-26:

• La tabla es syslog, no sys_log (sys_log devuelve 400 Invalid table sys_log).

• syslog.level es numérico, no las cadenas "warning"/"error": -2=Trace, -1=Debug, 0=Information, 1=Warning, 2=Error, 3=Fatal (confirmado mediante GET /api/now/table/sys_choice?sysparm_query=name=syslog^element=level).

• El filtro de rango de fechas debe usar literales de fecha y hora simples ('<date> 00:00:00'@'<date> 23:59:59'), no javascript:gs.dateGenerate(...) — consulta Resolución de problemas para ver por qué este último desplazaba silenciosamente los resultados al día equivocado.

src/tools/syslog.ts asigna internamente los nombres de nivel descriptivos ("warning", "error", etc.) a estos códigos, de modo que quienes la invocan pueden seguir pasando nombres — esto solo importa si extiendes la herramienta o la apuntas a una instancia distinta, donde el mapeo debería re-verificarse con la misma consulta sys_choice.

5. Registrar en Claude Code CLI

claude mcp add --scope user servicenow-reports -- "C:\Program Files\nodejs\node.exe" C:\Users\willr\projects\servicenow-mcp-reports\dist\index.js

Usa la ruta absoluta a node.exe, no node a secas — una sesión de Claude Code iniciada antes de que Node estuviera en PATH no podrá resolver un comando node a secas al lanzar el servidor (claude mcp list mostrará CONNECTION_CLOSED). Verifícalo con claude mcp list.

Claude Code CLI lee SN_INSTANCE/SN_USER/SN_PASS desde .env en la carpeta de este proyecto — no se necesita configuración de env adicional en el lado de la CLI siempre que .env exista aquí. Esto depende de que src/index.ts resuelva la ruta de .env en relación con el propio script compilado (import.meta.url), no process.cwd() — un simple import "dotenv/config" fallaría, porque Claude Code lanza este servidor desde un directorio de trabajo no relacionado. Consulta Resolución de problemas si parece que .env deja de cargarse.

6. Registrar con Claude Desktop

Añade a %APPDATA%\Claude\claude_desktop_config.json (creado de cero — no existía en esta máquina):

{
  "mcpServers": {
    "servicenow-reports": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\willr\\projects\\servicenow-mcp-reports\\dist\\index.js"],
      "env": {
        "SN_INSTANCE": "https://dev203275.service-now.com",
        "SN_USER": "claude_mcp_readonly",
        "SN_PASS": "<password>"
      }
    }
  }
}

Claude Desktop lanza el servidor como un proceso propio sin heredar el .env de este proyecto, por lo que las credenciales se repiten aquí explícitamente. Reinicia Claude Desktop después de editar y luego comprueba el icono de conector 🔌 para confirmar que se conectó.

7. Opcional: transporte HTTP accesible de forma remota

Los pasos 5–6 usan stdio, que solo funciona para un cliente que pueda lanzar un proceso local (Claude Code, Claude Desktop). Un cliente que no pueda — p. ej. las Scheduled Tasks alojadas de claude.ai — necesita en su lugar un endpoint HTTP. src/http.ts expone las mismas dos herramientas sobre el transporte Streamable HTTP de MCP en POST/GET /mcp.

npm run build
$env:MCP_HTTP_TOKEN="<pick something random>"; npm run start:http

Valores por defecto: se vincula a 127.0.0.1:3535 (se puede sobrescribir con MCP_HTTP_HOST / MCP_HTTP_PORT en .env). Si MCP_HTTP_TOKEN está definido, cada solicitud debe enviar Authorization: Bearer <token> o recibe 401; si no está definido, el servidor registra una advertencia y acepta solicitudes no autenticadas — correcto mientras esté vinculado solo a localhost, no correcto si alguna vez queda detrás de un túnel público. createMcpExpressApp() (del SDK) también activa automáticamente la protección contra DNS-rebinding siempre que esté vinculado a un host localhost.

Para alcanzarlo realmente desde las Scheduled Tasks alojadas de claude.ai, 127.0.0.1 no basta — necesita una URL pública (p. ej. un túnel: ngrok http 3535, o un despliegue real). Eso es un paso aparte, no realizado aquí; esto solo añade la capacidad. Haz primero una prueba de humo local:

curl.exe -s -X POST http://127.0.0.1:3535/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer $env:MCP_HTTP_TOKEN" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoketest","version":"0.0.1"}}}'

Debería devolver 200 con una cabecera de respuesta mcp-session-id y un cuerpo JSON-RPC result.

Resolución de problemas

• 401 en cada llamada REST a pesar de una contraseña correcta, pero iniciar sesión en la UI de ServiceNow con las mismas credenciales funciona — esto es SNCRestrictBasicAuthUserAuthenticationGate: bloquea la autenticación Basic por REST para cuentas que también pueden iniciar sesión interactivamente. Solución: marca "Web service access only" en el registro de usuario (paso 1). No pierdas tiempo restableciendo la contraseña otra vez — ese patrón (inicio de sesión en la UI OK, REST 401, "User is not authenticated" / "Required to provide Auth information") es esta compuerta, no una credencial incorrecta. Se puede diagnosticar directamente desde System Logs (/syslog_list.do, filtrando por el nombre de la cuenta).

• Invalid table sys_log (HTTP 400) — la tabla es syslog, sin guion bajo.

• El informe vuelve vacío aunque existan logs para ese día — level es numérico en esta instancia (consulta el paso 4), no las cadenas "warning"/"error". Revisa el mapeo mediante la consulta sys_choice si apuntas esto a una instancia distinta.

• Missing SN_INSTANCE, SN_USER, or SN_PASS environment variables" cuando se lanza como un servidor MCP real, aunque .env exista y una prueba directa de node dist/index.js desde esta carpeta funcione bien — esa prueba directa tiene éxito porque su process.cwd() resulta ser la carpeta del proyecto; Claude Code lanza el servidor desde otro lugar, por lo que dotenv/config a secas falla silenciosamente. Confirma que src/index.ts resuelve .env mediante import.meta.url, no cwd (consulta el paso 5). Verifica siempre con una llamada real a una herramienta MCP, no solo con una ejecución directa del script — los dos pueden no coincidir.

• get_syslog_report devuelve silenciosamente el día equivocado / le faltan varias horas — fue un bug real, encontrado el 2026-08-26 mediante una comprobación puntual comparando con los patrones de consulta de echelon-ai-labs/servicenow-mcp. src/tools/syslog.ts solía construir el filtro de fecha con sys_created_onBETWEENjavascript:gs.dateGenerate('<date>','00:00:00')@javascript:gs.dateGenerate(...). gs.dateGenerate() evalúa en la zona horaria configurada de la instancia, pero sys_created_on se devuelve como un valor UTC crudo a través de la Table API — por lo que la ventana se desplazaba silenciosamente por el delta UTC de la instancia (~7h en este PDI), arrastrando la cola del día equivocado y perdiendo las primeras horas del correcto. Corregido eliminando por completo el envoltorio javascript:gs.dateGenerate(...) y pasando cadenas literales simples '<date> 00:00:00'@'<date> 23:59:59', que se comparan directamente con el valor almacenado crudo sin conversión de zona horaria. Verificado: 834 filas en las 24 horas completas para 2026-08-25, frente a 366 filas en 17 horas antes de la corrección. Si la configuración de zona horaria de esta instancia cambia alguna vez, vuelve a verificarlo con la misma comprobación de cobertura de todas las horas (consulta la comprobación puntual estilo paso 4) en lugar de asumir.

• CONNECTION_CLOSED en claude mcp list — la sesión de la CLI se inició antes de que Node.js estuviera en PATH. Registra con la ruta absoluta de node.exe (ya hecho en el paso 5) o inicia una sesión nueva.

• Se editó el código, se recompiló, pero el comportamiento no cambió — una sesión de Claude Code ya en ejecución mantiene el dist/ antiguo cargado sobre su conexión stdio. Ejecuta /mcp en esa sesión para reconectar; no hace falta reiniciar.

Archivos

• src/servicenow-client.ts — envoltorio de la Table API (autenticación Basic) más queryTableAll, el bucle de paginación que usan ambas herramientas (1000 filas/página, tope de seguridad de 10 000 filas, devuelve { rows, truncated }). Cambia aquí la autenticación Basic por OAuth más adelante si sales del PDI.

• src/tools/syslog.ts, src/tools/dev-work-report.ts — las dos consultas de informes.

• src/create-server.ts — construye un McpServer y registra ambas herramientas; compartido por los dos puntos de entrada siguientes.

• src/index.ts — punto de entrada stdio (Claude Code/Desktop); resuelve .env en relación consigo mismo (no con cwd).

• src/http.ts — punto de entrada Streamable HTTP (paso 7); autenticación con bearer token, un servidor+transporte por sesión.