servicenow-devtools-mcp

MCP do ServiceNow Platform

Use seu aplicativo de IA para trabalhar com chamados do ServiceNow, entender sua instância e preparar alterações em registros ou scripts.

MCP (Model Context Protocol) permite que um aplicativo de IA use ferramentas de outro sistema. Este servidor conecta essas ferramentas à sua instância do ServiceNow. Você descreve o trabalho em linguagem natural, e o aplicativo chama as ferramentas necessárias.

Você faz login com sua conta do ServiceNow. Seus papéis, políticas de acesso à API e regras de controle de acesso (ACLs) continuam determinando o que você pode ler ou alterar.

Comece aqui

• Trabalhando com chamados e solicitações? Comece com Trabalho de ITSM.
• Administrando ou desenvolvendo uma instância? Comece com administração e desenvolvimento de instância.
• Conectando pela primeira vez? Siga a configuração de conexão, ou pergunte ao seu administrador pela configuração.

Se o seu aplicativo de IA já tiver este servidor configurado, tente:

Use o ServiceNow para mostrar 5 incidentes ativos que eu possa acessar. Inclua o número do incidente, descrição curta, prioridade e pessoa designada. Não altere nada.

A primeira solicitação que precisar do ServiceNow abrirá seu navegador para login e permissão de conexão. Use o navegador no computador que executa o servidor MCP.

Trabalho de ITSM

Leia registros de incidentes, problemas, mudanças e solicitações. Revise o histórico de chamados, inspecione anexos ou conte registros para uma atualização de status. Você pode pedir o resultado como lista, tabela ou resumo.

Por exemplo:

• "Mostre 10 incidentes ativos atribuídos ao grupo Service Desk, ordenados por prioridade."
• "Resuma INC0012345, incluindo comentários e notas de trabalho dos últimos 30 dias."
• "Conte incidentes abertos por grupo de atribuição. Inclua os filtros usados."
• "Mostre as respostas enviadas com RITM0012345."

Substitua números de exemplo e nomes de grupos pelos valores da sua instância. Informe um período de tempo e um limite ao pedir uma lista ou histórico. Peça ao aplicativo para incluir números de registro para que você possa verificar a resposta no ServiceNow.

Criar chamados, atualizar notas de trabalho e alterar atribuições exigem ferramentas de escrita e permissões do ServiceNow. Veja fazendo alterações.

Administração e desenvolvimento de instância

Use o MCP para inspecionar como sua instância funciona, investigar problemas e preparar alterações na configuração do ServiceNow. Você pode começar com um nome de registro ou uma pergunta. Você não precisa escrever solicitações de API ou conhecer os nomes das ferramentas MCP.

Por exemplo:

• "Leia a Regra de negócio chamada 'Validar prioridade'. Explique quando ela é executada e o que seu script faz."
• "Encontre scripts que chamam gs.eventQueue. Mostre os registros correspondentes."
• "Inspecione o fluxo 'Novo funcionário'. Explique seu gatilho e etapas configuradas."
• "Investigue erros de script das últimas 24 horas. Mostre as evidências de cada descoberta."

Substitua nomes de regras e fluxos de exemplo pelos registros da sua instância.

Os resultados de diagnóstico ajudam você a investigar uma causa. Eles não estabelecem uma causa raiz nem reparam automaticamente a instância. As ferramentas do Flow Designer inspecionam a configuração armazenada. Elas não editam, publicam ou executam fluxos.

Com as ferramentas de escrita habilitadas, você pode criar ou atualizar registros de configuração, incluindo campos de script. Siga o fluxo de trabalho de mudanças antes de aplicar uma alteração de script.

Configuração de conexão

Um administrador prepara a conexão do ServiceNow. Cada usuário então autoriza o acesso com sua própria conta do ServiceNow.

A conexão suportada é executada localmente no seu computador. Seu aplicativo de IA inicia o servidor usando stdio, uma conexão local entre os dois programas. Você precisa de Python 3.14 ou posterior, uv, e um aplicativo de IA que possa iniciar servidores MCP locais.

1. Prepare o OAuth no ServiceNow

O OAuth permite que os usuários autorizem a conexão pelo navegador. O ID do cliente público identifica o aplicativo. Não é uma senha ou um segredo de cliente.

Abra System OAuth > Application Registry. Selecione New, depois Create an OAuth API endpoint for external clients, ou selecione um aplicativo de entrada existente. Configure o aplicativo para atender a estes requisitos:

Salve o aplicativo. Copie o ID do cliente público para o próximo passo. Se você não puder configurar o OAuth, peça ao administrador do ServiceNow para fornecer esse ID e a URL da instância.

Os usuários precisam de acesso à API para os registros necessários ao seu trabalho. O OAuth não concede permissões adicionais de tabela ou campo.

2. Adicione a conexão ao seu aplicativo de IA

Substitua https://your-instance.service-now.com e your-public-client-id pelos valores fornecidos pelo seu administrador. Use o endereço HTTPS da instância sem um caminho de página, como /nav_to.do.

Estes exemplos selecionam explicitamente readonly e bloqueiam gravações com SERVICENOW_ENV=prod. A configuração de ambiente controla a proteção contra gravação. Ela não seleciona uma instância nem detecta se essa instância é de produção.

Mantenha as entradas de servidor existentes ao adicionar esta configuração. Não adicione senhas, chaves de API, segredos de cliente ou tokens.

VS Code com GitHub Copilot, ou Claude Code

Salve esta configuração como .mcp.json na pasta de nível superior que você abre no seu aplicativo de IA:

{
  "mcpServers": {
    "servicenow-platform": {
      "command": "uvx",
      "args": [
        "servicenow-platform-mcp"
      ],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_OAUTH_CLIENT_ID": "your-public-client-id",
        "MCP_TOOL_PACKAGE": "readonly",
        "SERVICENOW_ENV": "prod"
      }
    }
  }
}

No VS Code, abra o Chat e habilite as ferramentas do ServiceNow. No Claude Code, aprove o servidor MCP do projeto quando solicitado. Para configuração em todo o usuário e controles de conexão, veja o guia do VS Code ou guia do Claude Code.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servicenow-platform": {
      "type": "local",
      "command": [
        "uvx",
        "servicenow-platform-mcp"
      ],
      "enabled": true,
      "environment": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_OAUTH_CLIENT_ID": "your-public-client-id",
        "MCP_TOOL_PACKAGE": "readonly",
        "SERVICENOW_ENV": "prod"
      }
    }
  }
}

Para outro aplicativo MCP local, use o comando uvx servicenow-platform-mcp com as mesmas quatro variáveis de ambiente. O formato de configuração pode diferir. O guia de instalação inclui uma entrada de servidor que você pode adaptar.

3. Faça login e verifique o acesso

1. Reinicie seu aplicativo de IA ou o servidor MCP do ServiceNow após salvar a configuração.
2. Pergunte: "Liste as ferramentas disponíveis do ServiceNow."
3. Pergunte: "Use o ServiceNow para mostrar um incidente ativo. Inclua seu número e descrição curta."
4. Conclua a autorização no navegador com a conta pretendida do ServiceNow.

Um registro retornado confirma que a conexão pode ler essa tabela. Se você não puder ler incidentes, use uma tabela que sua conta possa acessar. A descoberta de ferramentas sozinha não confirma uma conexão funcional com o ServiceNow.

Os tokens permanecem na memória do servidor. O servidor renova um token de acesso expirado quando pode. Reiniciar o servidor exige autorização pelo navegador novamente.

Fazendo alterações

Comece com uma instância de desenvolvimento ou teste. Peça ao seu administrador para habilitar apenas as ferramentas de escrita necessárias para o seu trabalho e conceder as permissões correspondentes do ServiceNow.

Por exemplo, MCP_TOOL_PACKAGE=query,describe,record_read,record_write habilita inspeção e alterações de registros. Defina SERVICENOW_ENV=dev para essa instância que não é de produção. Reinicie o servidor após alterar a configuração.

Toda mutação de registro, anexo e catálogo exige pré-visualização seguida de mutation_apply. O servidor não impõe aprovação humana. Use este processo de revisão:

1. Peça ao aplicativo para ler o registro atual.
2. Peça uma pré-visualização da alteração proposta.
3. Revise a instância de destino, o registro, os valores dos campos e as diferenças de script.
4. Diga ao aplicativo para aplicar essa pré-visualização somente quando você aprovar.
5. Verifique o resultado no ServiceNow. Teste qualquer comportamento alterado na instância.

Para uma atualização de chamado:

Pré-visualize a adição desta nota de trabalho ao INC0012345: "Aguardando o chamador confirmar a correção." Mostre a alteração proposta e aguarde minha aprovação.

Para uma atualização de script:

Leia a Regra de negócio chamada 'Validar prioridade'. Sugira uma correção e explique-a. Mostre uma pré-visualização com o script de substituição completo. Aguarde minha aprovação antes de aplicá-la.

record_preview, attachment_preview e service_catalog_preview retornam tokens de uso único. mutation_apply consome um token revisado e verifica política, autorização e alterações de estado detectáveis. Os tokens expiram após 300 segundos e desaparecem na reinicialização. Se um resultado remoto for desconhecido, verifique o ServiceNow antes de criar outra pré-visualização.

A navegação no catálogo está disponível em readonly até service_catalog. As pré-visualizações de mutação de catálogo exigem o grupo service_catalog_write. A pré-visualização não simula o atendimento nem garante preços.

Atualizações de script substituem o valor completo do campo. O servidor não verifica a sintaxe do JavaScript. Revise e teste o script antes de confiar em seu comportamento.

Defina SERVICENOW_ENV=prod ou production para conexões de produção a fim de bloquear gravações por meio deste servidor. As permissões do ServiceNow continuam sendo a autoridade para acesso a registros. A seleção de ferramentas e as configurações de ambiente são controles locais adicionais.

Escolha as ferramentas disponíveis

MCP_TOOL_PACKAGE controla quais ferramentas seu aplicativo de IA pode chamar:

O pacote padrão é readonly e o ambiente padrão é prod. Um pacote habilita ferramentas. Ele não concede permissões do ServiceNow. list_tool_packages lista pacotes e grupos disponíveis, não o pacote ativo. Para o inventário completo e entradas de ferramentas, veja a referência de ferramentas.

Se algo não funcionar

Para uma solicitação com falha, inclua a ação, o registro ou tabela e o erro sanitizado no seu relatório. Exclua senhas, tokens, cabeçalhos brutos e URLs de retorno do navegador. Veja solução de problemas de instalação para verificações mais detalhadas.

Os dados do ServiceNow retornados pelas ferramentas ficam disponíveis para seu aplicativo de IA. Use um aplicativo aprovado para os dados que você manipula.

Mais ajuda

• Trabalho de ITSM: filas de chamados, histórico, respostas de solicitações e alterações de chamados.
• Administração e desenvolvimento de instância: tabelas, scripts, fluxos, investigações e alterações revisadas.
• Instalação e configuração: configuração de conexão, instalação a partir da fonte e solução de problemas.
• Wiki completo: configurações, referência de ferramentas, limites de segurança e diagnósticos.
• Contribuindo para este servidor MCP: desenvolvimento local, testes e versões.

Relatar um problema · Pacote PyPI · Licença MIT