Servidor MCP de ServiceNow

Una implementación de servidor de Protocolo de finalización de modelo (MCP) para ServiceNow, que permite a Claude interactuar con instancias de ServiceNow.

Descripción general

Este proyecto implementa un servidor MCP que permite a Claude conectarse a instancias de ServiceNow, recuperar datos y realizar acciones a través de la API de ServiceNow. Actúa como puente entre Claude y ServiceNow, lo que permite una integración fluida.

Características

• Conéctese a instancias de ServiceNow utilizando varios métodos de autenticación (básico, OAuth, clave API)
• Consultar registros y tablas de ServiceNow
• Crear, actualizar y eliminar registros de ServiceNow
• Ejecutar scripts y flujos de trabajo de ServiceNow
• Acceder y consultar el catálogo de servicios de ServiceNow
• Analizar y optimizar el catálogo de servicios de ServiceNow
• Modo de depuración para la resolución de problemas
• Soporte para comunicación stdio y eventos enviados por el servidor (SSE)

Instalación

Prerrequisitos

• Python 3.11 o superior
• Una instancia de ServiceNow con credenciales de acceso adecuadas

Configuración

1. Clonar este repositorio:
   git clone https://github.com/yourusername/servicenow-mcp.git cd servicenow-mcp
2. Cree un entorno virtual e instale el paquete:
   python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate pip install -e .
3. Cree un archivo .env con sus credenciales de ServiceNow:
   SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com SERVICENOW_USERNAME=your-username SERVICENOW_PASSWORD=your-password SERVICENOW_AUTH_TYPE=basic # or oauth, api_key

Uso

Modo estándar (stdio)

Para iniciar el servidor MCP:

O con variables de entorno:

Modo de eventos enviados por el servidor (SSE)

El servidor MCP de ServiceNow también puede ejecutarse como un servidor web utilizando eventos enviados por el servidor (SSE) para la comunicación, lo que permite opciones de integración más flexibles.

Iniciar el servidor SSE

Puede iniciar el servidor SSE utilizando la CLI proporcionada:

De forma predeterminada, el servidor escuchará en 0.0.0.0:8080 . Puedes personalizar el host y el puerto:

Conexión al servidor SSE

El servidor SSE expone dos puntos finales principales:

• /sse - El punto final de la conexión SSE
• /messages/ - El punto final para enviar mensajes al servidor

Ejemplo

Consulte el archivo examples/sse_server_example.py para obtener un ejemplo completo de cómo configurar y ejecutar el servidor SSE.

Herramientas disponibles

El servidor MCP de ServiceNow proporciona las siguientes herramientas:

Herramientas de gestión de incidentes

1. create_incident - Crea un nuevo incidente en ServiceNow
2. update_incident - Actualizar un incidente existente en ServiceNow
3. add_comment - Agregar un comentario a un incidente en ServiceNow
4. resolve_incident - Resolver un incidente en ServiceNow
5. list_incidents - Lista de incidentes de ServiceNow

Herramientas del catálogo de servicios

1. list_catalog_items : lista de elementos del catálogo de servicios de ServiceNow
2. get_catalog_item : obtiene un elemento específico del catálogo de servicios de ServiceNow
3. list_catalog_categories : lista de categorías del catálogo de servicios de ServiceNow
4. create_catalog_category : crea una nueva categoría de catálogo de servicios en ServiceNow
5. update_catalog_category : actualiza una categoría del catálogo de servicios existente en ServiceNow
6. move_catalog_items - Mueve elementos del catálogo entre categorías en ServiceNow
7. create_catalog_item_variable - Crea una nueva variable (campo de formulario) para un artículo del catálogo
8. list_catalog_item_variables : enumera todas las variables de un artículo del catálogo
9. update_catalog_item_variable - Actualizar una variable existente para un artículo del catálogo

Herramientas de optimización de catálogos

1. get_optimization_recommendations - Obtenga recomendaciones para optimizar el catálogo de servicios
2. update_catalog_item - Actualizar un elemento del catálogo de servicios

Herramientas de gestión del cambio

1. create_change_request - Crea una nueva solicitud de cambio en ServiceNow
2. update_change_request - Actualizar una solicitud de cambio existente
3. list_change_requests : lista de solicitudes de cambio con opciones de filtrado
4. get_change_request_details : obtener información detallada sobre una solicitud de cambio específica
5. add_change_task - Agregar una tarea a una solicitud de cambio
6. submit_change_for_approval - Enviar una solicitud de cambio para su aprobación
7. approved_change - Aprobar una solicitud de cambio
8. reject_change - Rechazar una solicitud de cambio

Herramientas de gestión del flujo de trabajo

1. list_workflows - Lista de flujos de trabajo de ServiceNow
2. get_workflow : obtener un flujo de trabajo específico de ServiceNow
3. create_workflow - Crea un nuevo flujo de trabajo en ServiceNow
4. update_workflow - Actualizar un flujo de trabajo existente en ServiceNow
5. delete_workflow - Eliminar un flujo de trabajo de ServiceNow

Herramientas de administración de inclusión de scripts

1. list_script_includes - Lista de scripts incluidos en ServiceNow
2. get_script_include - Obtener un script específico incluido desde ServiceNow
3. create_script_include - Crea un nuevo script incluido en ServiceNow
4. update_script_include - Actualizar un script existente incluido en ServiceNow
5. delete_script_include - Eliminar un script incluido de ServiceNow

Herramientas de gestión de conjuntos de cambios

1. list_changesets : lista de conjuntos de cambios de ServiceNow con opciones de filtrado
2. get_changeset_details : obtener información detallada sobre un conjunto de cambios específico
3. create_changeset - Crea un nuevo conjunto de cambios en ServiceNow
4. update_changeset - Actualizar un conjunto de cambios existente
5. commit_changeset - Confirmar un conjunto de cambios
6. publish_changeset - Publicar un conjunto de cambios
7. add_file_to_changeset - Agregar un archivo a un conjunto de cambios

Herramientas de gestión de bases de conocimientos

1. create_knowledge_base - Crea una nueva base de conocimiento en ServiceNow
2. list_knowledge_bases - Lista de bases de conocimiento con opciones de filtrado
3. create_category - Crea una nueva categoría en una base de conocimiento
4. create_article - Crea un nuevo artículo de conocimiento en ServiceNow
5. update_article - Actualizar un artículo de conocimiento existente en ServiceNow
6. publish_article - Publicar un artículo de conocimiento en ServiceNow
7. list_articles - Lista de artículos de conocimiento con opciones de filtrado
8. get_article - Obtener un artículo de conocimiento específico por ID

Herramientas de gestión de usuarios

1. create_user - Crea un nuevo usuario en ServiceNow
2. update_user - Actualizar un usuario existente en ServiceNow
3. get_user - Obtener un usuario específico por ID, nombre de usuario o correo electrónico
4. list_users - Lista de usuarios con opciones de filtrado
5. create_group - Crea un nuevo grupo en ServiceNow
6. update_group - Actualizar un grupo existente en ServiceNow
7. add_group_members - Agregar miembros a un grupo en ServiceNow
8. remove_group_members - Eliminar miembros de un grupo en ServiceNow
9. list_groups - Lista de grupos con opciones de filtrado

Uso de la CLI de MCP

El servidor MCP de ServiceNow se puede instalar con la CLI de MCP, lo que proporciona una forma conveniente de registrar el servidor con Claude.

Este comando registrará el servidor MCP de ServiceNow con Claude y lo configurará para utilizar las variables de entorno del archivo .env.

Integración con Claude Desktop

Para configurar el servidor MCP de ServiceNow en Claude Desktop:

1. Edite el archivo de configuración de Claude Desktop en ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o la ruta adecuada para su sistema operativo:

2. Reinicie Claude Desktop para aplicar los cambios

Ejemplo de uso con Claude

Una vez que el servidor ServiceNow MCP esté configurado con Claude Desktop, puede pedirle a Claude que realice acciones como:

Ejemplos de gestión de incidentes

• Crear un nuevo incidente por una interrupción de red en la región este.
• "Actualizar la prioridad del incidente INC0010001 a alta"
• "Añadir un comentario al incidente INC0010001 indicando que se está investigando el problema"
• "Resolver el incidente INC0010001 con una nota indicando que se reinició el servidor"
• "Enumere todos los incidentes de alta prioridad asignados al equipo de Red"

Ejemplos de catálogos de servicios

• "Muéstrame todos los artículos del catálogo de servicios"
• "Enumerar todas las categorías del catálogo de servicios"
• Obtener detalles sobre el artículo del catálogo de solicitud de portátil
• "Muéstrame todos los artículos del catálogo de la categoría Hardware"
• "Buscar 'software' en el catálogo de servicios"
• "Crear una nueva categoría llamada 'Servicios en la nube' en el catálogo de servicios"
• Actualizar la categoría 'Hardware' para renombrarla como 'Equipo de TI'.
• "Mover el elemento del catálogo 'Máquina Virtual' a la categoría 'Servicios en la Nube'"
• Cree una subcategoría llamada "Monitores" dentro de la categoría "Equipos de TI".
• Reorganizar nuestro catálogo moviendo todos los artículos de software a la categoría "Software".
• "Crear un campo de descripción para el artículo del catálogo de solicitud de portátil"
• "Añadir un campo desplegable para seleccionar modelos de portátiles al catálogo"
• "Enumerar todos los campos del formulario para el elemento del catálogo de solicitud de acceso VPN"
• "Hacer que el campo de departamento sea obligatorio en el formulario de solicitud de software"
• "Actualizar el texto de ayuda para el campo del centro de coste"

Ejemplos de optimización de catálogos

• Analizar nuestro catálogo de servicios e identificar oportunidades de mejora.
• "Encuentre artículos del catálogo con descripciones deficientes que necesitan mejoras"
• Identificar los artículos del catálogo con poco uso que podríamos querer retirar.
• Encuentra artículos del catálogo con altas tasas de abandono.
• Optimizar nuestra categoría de hardware para mejorar la experiencia del usuario.

Ejemplos de gestión del cambio

• "Crear una solicitud de cambio para que el mantenimiento del servidor aplique parches de seguridad mañana por la noche"
• "Programar una actualización de la base de datos para el próximo martes de 2 a. m. a 4 a. m."
• "Añadir una tarea al cambio de mantenimiento del servidor para las comprobaciones previas a la implementación"
• "Enviar el cambio de mantenimiento del servidor para su aprobación"
• "Aprobar el cambio de actualización de la base de datos con el comentario: el plan de implementación parece completo"
• "Muéstrame todos los cambios de emergencia programados para esta semana"
• "Enumerar todos los cambios asignados al equipo de Red"

Ejemplos de gestión del flujo de trabajo

• "Muéstrame todos los flujos de trabajo activos en ServiceNow"
• Obtenga detalles sobre el flujo de trabajo de aprobación de incidentes.
• "Enumerar todas las versiones del flujo de trabajo de solicitud de cambio"
• "Muéstrame todas las actividades en el flujo de trabajo de solicitud del catálogo de servicios"
• Crear un nuevo flujo de trabajo para gestionar las solicitudes de licencias de software
• Actualizar la descripción del flujo de trabajo de escalamiento de incidentes.
• Activar el flujo de trabajo de incorporación de nuevos empleados
• "Desactivar el flujo de trabajo de restablecimiento de contraseña antigua"
• Agregar una actividad de aprobación al flujo de trabajo de solicitud de licencia de software
• Actualizar la actividad de notificación en el flujo de trabajo de escalamiento de incidentes.
• Eliminar la actividad innecesaria del flujo de trabajo de solicitud de cambio
• Reordenar las actividades en el flujo de trabajo de solicitud del catálogo de servicios

Ejemplos de gestión de conjuntos de cambios

• "Enumerar todos los conjuntos de cambios en ServiceNow"
• "Muéstrame todos los conjuntos de cambios creados por el desarrollador 'john.doe'"
• Obtener detalles sobre el conjunto de cambios 'sys_update_set_123'
• Crear un nuevo conjunto de cambios para la aplicación 'Portal de RR. HH.'
• "Actualizar la descripción del conjunto de cambios 'sys_update_set_123'"
• "Confirmar el conjunto de cambios 'sys_update_set_123' con el mensaje 'Problema de inicio de sesión solucionado'"
• "Publicar el conjunto de cambios 'sys_update_set_123' en producción"
• "Añadir un archivo al conjunto de cambios 'sys_update_set_123'"
• "Muéstrame todos los cambios en el conjunto de cambios 'sys_update_set_123'"

Ejemplos de bases de conocimientos

• "Crear una nueva base de conocimientos para el departamento de TI"
• "Enumerar todas las bases de conocimiento de la organización"
• Crear una categoría llamada "Solución de problemas de red" en la base de conocimientos de TI.
• "Escribe un artículo sobre la configuración de VPN en la categoría de Solución de problemas de red".
• Actualizar el artículo de configuración de VPN para incluir instrucciones para dispositivos móviles.
• Publicar el artículo de configuración de VPN para que sea visible para todos los usuarios.
• "Enumerar todos los artículos de la categoría Solución de problemas de red"
• "Muéstrame los detalles del artículo de configuración de VPN"
• Encuentre artículos de conocimiento que contengan "restablecimiento de contraseña" en la base de conocimientos de TI.
• Cree una subcategoría llamada "Redes inalámbricas" dentro de la categoría "Solución de problemas de red".

Ejemplos de gestión de usuarios

• Crear un nuevo usuario: Dra. Alice Radiology, en el departamento de Radiología.
• "Actualizar el registro de usuario de Bob para convertirlo en el administrador de Alice"
• Asignar el rol de ITIL a Bob para que pueda aprobar las solicitudes de cambio.
• "Enumerar todos los usuarios del departamento de Radiología"
• Crear un nuevo grupo llamado 'Ingeniería Biomédica' para la gestión de dispositivos médicos.
• "Agregar un usuario administrador al grupo de Ingeniería Biomédica como miembro"
• "Actualizar el grupo de Ingeniería Biomédica para cambiar de responsable"
• Eliminar un usuario del grupo de Ingeniería Biomédica
• "Buscar todos los usuarios activos en el sistema que tengan la palabra 'doctor' en su título"
• "Crear un usuario que actuará como aprobador del departamento de Radiología"
• "Enumerar todos los grupos de soporte de TI en el sistema"

Scripts de ejemplo

El repositorio incluye scripts de ejemplo que demuestran cómo utilizar las herramientas:

• examples/catalog_optimization_example.py : Demuestra cómo analizar y mejorar el catálogo de servicios de ServiceNow
• examples/change_management_demo.py : Muestra cómo crear y administrar solicitudes de cambio en ServiceNow

Métodos de autenticación

Autenticación básica

Autenticación OAuth

Autenticación de clave API

Desarrollo

Documentación

Hay documentación adicional disponible en el directorio docs :

• Integración del catálogo : información detallada sobre la integración del catálogo de servicios
• Optimización del catálogo : plan detallado para las funciones de optimización del catálogo
• Gestión del cambio : información detallada sobre las herramientas de gestión del cambio
• Gestión del flujo de trabajo : información detallada sobre las herramientas de gestión del flujo de trabajo
• Gestión de conjuntos de cambios : información detallada sobre las herramientas de gestión de conjuntos de cambios

Solución de problemas

Errores comunes con las herramientas de gestión de cambios

1. Error: argument after ** must be a mapping, not CreateChangeRequestParams
   • Este error se produce cuando se pasa un objeto CreateChangeRequestParams en lugar de un diccionario a la función create_change_request .
   • Solución: asegúrese de que está pasando un diccionario con los parámetros, no un objeto de modelo Pydantic.
   • Nota: Las herramientas de gestión de cambios se han actualizado para gestionar este error automáticamente. Las funciones ahora intentarán desempaquetar los parámetros si están incorrectamente empaquetados o se pasan como un objeto de modelo de Pydantic.
2. Error: Missing required parameter 'type'
   • Este error ocurre cuando no proporciona todos los parámetros necesarios para crear una solicitud de cambio.
   • Solución: Asegúrese de incluir todos los parámetros obligatorios. Para create_change_request , se requieren short_description y type .
3. Error: Invalid value for parameter 'type'
   • Este error se produce cuando se proporciona un valor no válido para el parámetro type .
   • Solución: utilice uno de los valores válidos: “normal”, “estándar” o “emergencia”.
4. Error: Cannot find get_headers method in either auth_manager or server_config
   • Este error ocurre cuando los parámetros se pasan en el orden incorrecto o cuando se utilizan objetos que no tienen los métodos requeridos.
   • Solución: Asegúrese de pasar los parámetros auth_manager y server_config en el orden correcto. Las funciones se han actualizado para gestionar el intercambio automático de parámetros.

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

1. Bifurcar el repositorio
2. Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
3. Confirme sus cambios ( git commit -m 'Add some amazing feature' )
4. Empujar a la rama ( git push origin feature/amazing-feature )
5. Abrir una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.