servicenow-mcp

Un pequeño servidor MCP que permite a los agentes de IA crear, buscar y actualizar incidencias de ServiceNow a través de la API de Tablas. Construido con el paquete oficial de Python mcp (decoradores estilo FastMCP), httpx y python-dotenv. Se ejecuta sobre stdio.

Todo reside en un único archivo: server.py.

Configuración

Requiere Python 3.12+ y uv.

uv sync

Crea un archivo .env junto a server.py (está ignorado por git) con credenciales de autenticación básica para tu instancia — una Instancia Personal de Desarrollador funciona bien:

SNOW_INSTANCE_URL=https://devXXXXXX.service-now.com
SNOW_USERNAME=admin
SNOW_PASSWORD=your-password
# optional, default 15
SNOW_TIMEOUT_SECONDS=15

Ejecuta el servidor (habla MCP sobre stdin/stdout, así que no hay nada que ver — un cliente MCP debe lanzarlo):

uv run server.py

Registro con un cliente MCP

Apunta el cliente a uv con el directorio del proyecto para que se recojan .venv y .env:

{
  "mcpServers": {
    "servicenow": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/servicenow-mcp", "run", "server.py"]
    }
  }
}

Para Claude Code: claude mcp add servicenow -- uv --directory /absolute/path/to/servicenow-mcp run server.py.

Las variables de entorno ya establecidas en el entorno del cliente tienen prioridad sobre .env.

Related MCP server: sn-mcp-bridge

Herramientas

Todas las herramientas lanzan un error legible de herramienta (mostrado al agente como isError) en lugar de un rastreo de pila, por ejemplo:

• Authentication failed (401): check SNOW_USERNAME and SNOW_PASSWORD. ServiceNow said: User is not authenticated …

• Could not connect to https://…: [Errno 8] nodename nor servname provided … Check SNOW_INSTANCE_URL and your network connection.

• Timed out after 15s talking to https://… The instance may be hibernating (PDI) or unreachable.

• Incident 'INC9999999' was not found on https://….

• Forbidden (403): the user lacks permission … or the update was rejected by a business rule. ServiceNow said: … (por ejemplo, resolver una incidencia sin campos de resolución).

Notas de diseño

• ServiceNowClient envuelve un único httpx.AsyncClient (autenticación básica, cabeceras JSON, tiempo de espera) y expone create_record / query_records / get_record_by_number / update_record. Todos los errores se traducen a ServiceNowError con un mensaje legible.

• Las herramientas obtienen el cliente a través de get_client(); llama a set_client(fake) en las pruebas para intercambiarlo por un mock sin tocar la red.

• Los registros se obtienen con sysparm_display_value=all, por lo que las etiquetas de estado/urgencia provienen de la propia instancia en lugar de un mapa codificado (los alias de nombres amigables son solo de entrada).

• mcp 2.x renombró FastMCP a MCPServer; server.py importa el que exista para que se ejecute tanto en 1.x como en 2.x.

Prueba de humo

Ejecuta contra la instancia en vivo (escribe una incidencia):

uv run python -c "
import asyncio, server
async def main():
    c = await server.create_incident('MCP server smoke test', 'created by smoke test')
    print(c)
    print(await server.query_incidents(query_text='MCP server smoke test'))
    print(await server.update_incident(c['number'], work_notes='hello from MCP'))
asyncio.run(main())
"