ServiceNow MCP

servicenow-mcp-ai — ServiceNow MCP Server

📖 Site de documentação →

Um servidor Model Context Protocol que permite que um cliente MCP (VS Code, Claude Desktop, etc.) execute comandos contra uma instância ServiceNow por meio de suas APIs REST — Table, Aggregate, Attachment, Import Set, Batch e CMDB, além das APIs de plugin Service Catalog, Change Management e Knowledge. As credenciais são mantidas em um arquivo de ambiente local e podem ser atualizadas em tempo de execução por meio de uma ferramenta.

Atualizando da versão 1.x? O v2.0 torna as escritas planejamento por padrão: create/update/delete e as outras ferramentas de escrita de registro retornam uma pré-visualização sem mutação, a menos que você passe apply: true (ou defina SN_WRITE_MODE=apply para restaurar o comportamento "executar imediatamente" do v1). Consulte o CHANGELOG → 2.0.0 para obter a nota de migração completa.

Conteúdo: Demonstração rápida · Recursos · Requisitos · Configuração · Configurar credenciais · Executar / depurar · Desenvolver · Ferramentas · Recursos · Prompts · Estrutura do projeto · Notas de segurança · Documentação do projeto · Suporte

Construído e mantido no meu próprio tempo — se ajudar, uma doação via GitHub Sponsors o mantém funcionando. Opções completas de Suporte estão perto do final.

Demonstração rápida

Três coisas que a plataforma torna difíceis, uma chamada para cada. Aponte seu cliente MCP para uma instância (Configuração) e pergunte:

1. "Onde este campo é realmente usado?" — cada script, regra de negócio, script de cliente, política/ação de UI e ACL que o referencia, como JSON ou um gráfico Mermaid. O "encontrar usos" de nível IDE que o ServiceNow não tem botão:

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

2. "O que é executado quando eu salvo este registro?" — a cadeia completa de automação em ordem de execução (regras de negócio display → before → after → assíncronas, depois fluxos, workflows e notificações), cada uma com sua condição — um teste lógico que executa nada:

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

3. "O que divergiu entre dev e prod?" — um diff em Markdown de tabelas, colunas, scripts (por SHA-256) e plugins entre dois perfis configurados, com um código de saída amigável para CI para que um pipeline possa bloquear uma implantação arriscada:

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

Todas as três são somente leitura e funcionam contra qualquer instância — incluindo um PDI gratuito — com o modelo e o cliente de sua escolha.

Recursos

• API Table completa: consultar, ler, criar, atualizar e excluir registros em qualquer tabela, com consultas codificadas, seleção de campos e paginação.
• APIs adicionais do ServiceNow: Aggregate (Stats), Attachment (listar/enviar/baixar/excluir), Import Set, Batch (muitas chamadas REST em um única solicitação), além de metadados de tabela/coluna (sys_db_object, sys_dictionary).
• APIs de processo e plugin: CMDB (CRUD de CI com classe + meta via IRE), Service Catalog (navegar/solicitar itens), Change Management (criação tipada + detecção de conflito) e Knowledge (pesquisa de artigos). APIs com escopo de plugin relatam claramente quando não estão ativas na instância.
• Inteligência de script: ler e pesquisar o código da própria instância (regras de negócio, includes de script, scripts de cliente, políticas/ações de UI, jobs agendados, scripts de transformação/REST, ACLs) e obter uma imagem completa da automação de uma tabela — tudo somente leitura via Table API.
• Rastreamento de fluxo e verificação de código (Fase 8): rastrear deterministicamente o que uma operação de tabela executa (pacote flows — regras de negócio, fluxos, workflows e notificações, em ordem, com um fluxograma Mermaid), ler fluxos do Flow Designer e histórico de execução, e verificar scripts com um conjunto de regras local e um relatório agregado de saúde de código (codecheck). Execute testes ATF via API CI/CD (atf, opt-in, não padrão — as ferramentas de execução executam na instância).
• Autodocumentação: uma base de conhecimento local em Markdown (ler/escrever/pesquisar) mais geradores Mermaid determinísticos (diagramas ER a partir de referências, fluxogramas de ciclo de vida de registro a partir de regras de negócio) para que o servidor construa contexto durável e reutilizável.
• Prompts: workflows prontos (triagem de incidentes, análise de impacto de mudança, documentar uma tabela) que orquestram as ferramentas.
• Pacotes de ferramentas: carregue apenas os grupos de ferramentas necessários via SN_TOOL_PACKAGES (perfil padrão core; all habilita tudo).
• Autenticação Basic ou OAuth 2.0 sobre HTTPS; a senha/token nunca é ecoada de volta.
• Controles de privilégio mínimo: listas de permitir/negar para tabelas e um modo somente leitura global.
• Resiliência: timeout por solicitação, nova tentativa com backoff e Retry-After, proteção SSRF, e uma proteção de tamanho de resultado.
• Anotações de ferramentas MCP e recursos, payloads de erro estruturados, e registro estruturado em stderr.
• Credenciais em um arquivo de ambiente (projeto, ~/.config, ou SN_ENV_FILE), atualizáveis em tempo de execução via servicenow_set_credentials.

Requisitos

• Node.js 20+ (imposto: engines + um guarda de tempo de execução com uma mensagem clara; o projeto tem como alvo a versão em .nvmrc).

Configuração

A partir do código-fonte (para desenvolvimento):

npm install
npm run build

Ou execute o pacote publicado diretamente, sem clonar:

npx servicenow-mcp-ai

Registre-o com um cliente MCP (Claude Desktop, VS Code Chat, o Inspector…) apontando o comando do servidor para npx:

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

Plugin Claude Code (zero-configuração — instala o servidor configurado):

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

VS Code — instale a extensão ServiceNow MCP do Marketplace (code --install-extension ivanbbaev.servicenow-mcp-ai); ela registra o servidor no Copilot Chat (modo agente) automaticamente, sem mcp.json manual. Código-fonte: extension/.

As credenciais são lidas de ~/.config/servicenow-mcp-ai/.env (ou variáveis de ambiente reais) — veja abaixo.

Início rápido

O caminho mais rápido é três linhas de autenticação Basic — defina estas (no arquivo de ambiente ou no ambiente real) e você estará conectado:

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

Todo o resto é ajuste opcional; consulte a referência completa de Variáveis de ambiente para o restante.

Além de uma tentativa rápida, prefira OAuth em vez de senha armazenada. Para qualquer coisa compartilhada ou de longa duração, execute o npx servicenow-mcp-ai login único em vez disso — ele armazena um refresh token, não sua senha. Consulte Configurar credenciais → OAuth 2.1.

Verificar sua configuração

Assim que as três variáveis estiverem definidas, confirme a conexão antes de começar:

1. Execute a ferramenta servicenow_test_connection — ela lê um registro sys_user e reporta ok, status HTTP e latência.
2. Execute servicenow_check_capabilities — ela pré-visualiza quais tabelas sys_* restritas a admin o usuário conectado pode ler de fato.

Ou faça os dois do shell de uma só vez:

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

Configurar credenciais

As credenciais vivem em .env na raiz do projeto (ignorado pelo git):

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

SN_INSTANCE aceita dev12345, dev12345.service-now.com ou uma URL https:// completa.

Você também pode definir ou alterá-las em tempo de execução chamando a ferramenta servicenow_set_credentials — os novos valores são gravados diretamente no arquivo de ambiente.

O arquivo de ambiente é resolvido nesta ordem: SN_ENV_FILE, depois ~/.config/servicenow-mcp-ai/.env (XDG) se presente, então o .env na raiz do projeto. Uma instalação global/npx grava, portanto, na configuração do usuário em vez de em node_modules. Variáveis de ambiente reais sempre têm precedência sobre o arquivo.

OAuth 2.1 (Authorization Code + PKCE) — recomendado

Registre um endpoint de API OAuth do tipo Authorization Code no ServiceNow com uma URL de redirecionamento loopback (por exemplo, http://localhost:53682/callback), defina SN_OAUTH_CLIENT_ID (e SN_OAUTH_CLIENT_SECRET para um cliente confidencial), e execute o login interativo único:

npx servicenow-mcp-ai login

Ele abre o navegador, você aprova, e o refresh token obtido é armazenado no seu arquivo de ambiente. O servidor então executa de forma não interativa (concessão refresh_token) — nenhuma senha é armazenada. PKCE (S256) é sempre usado.

A concessão de senha (ROPC) OAuth 2.0 está obsoleta no OAuth 2.1 e desabilitada em muitas instâncias; prefira login. As concessões client_credentials e refresh_token permanecem suportadas para contas de serviço. Veja .env.example.

Métodos de autenticação suportados

Toda método de autenticação REST de entrada que o ServiceNow oferece é coberto:

Método	SN_AUTH	Definido por	Notas
Basic	basic	SN_USER / SN_PASSWORD	Padrão.
OAuth 2.1 — Authorization Code + PKCE	oauth	npx servicenow-mcp-ai login	Recomendado. Interativo, armazena um refresh token.
OAuth — Client Credentials	oauth	SN_OAUTH_GRANT=client_credentials	Serviço a serviço.
OAuth — Refresh Token	oauth	SN_OAUTH_GRANT=refresh_token + SN_OAUTH_REFRESH_TOKEN	Definido por login.
OAuth — JWT Bearer	oauth	SN_OAUTH_GRANT=jwt_bearer + SN_OAUTH_JWT_KEY	Assinatura RS256; sem senha.
OAuth — Password (ROPC)	oauth	SN_OAUTH_GRANT=password	Obsoleto.
API Key	apikey	SN_API_KEY	Cabeçalho x-sn-apikey.
Bearer token	token	SN_BEARER_TOKEN	Token pré-obtido, usado literalmente.
Mutual TLS (certificado de cliente)	none (ou em camadas)	SN_TLS_CLIENT_CERT / _KEY	Certificado mapeia para um usuário; precisa de undici opcional.

Variáveis de ambiente

Todas as configurações são lidas de .env (ou do ambiente de processo real, que tem precedência). Apenas as três primeiras são obrigatórias; o restante são ajustes opcionais. Veja .env.example para um modelo.

Variável	Obrigatório	Padrão	Descrição
SN_INSTANCE	sim	—	Nome da instância, host ou URL https:// (dev12345, dev12345.service-now.com).
SN_USER	sim	—	Nome de usuário do ServiceNow para autenticação Basic.
SN_PASSWORD	sim	—	Senha do ServiceNow. Nunca registrada em logs nem retornada por nenhuma ferramenta.
SN_TIMEOUT_MS	não	30000	Tempo limite por requisição em milissegundos.
SN_MAX_RETRIES	não	2	Tentativas para falhas transitórias (429/5xx, erros de rede). Gravações não idempotentes só são repetidas em erros de conexão.
SN_MAX_RECORDS	não	10000	Limite máximo de registros retornados por uma consulta fetchAll.
SN_MAX_RESULT_CHARS	não	100000	Orçamento de caracteres para um resultado de consulta antes de ser truncado para o cliente.
SN_ALLOWED_HOSTS	não	—	Lista de permissão de hosts permitidos separada por vírgulas (para domínios personalizados ou de nuvem soberana). Quando definida, apenas hosts correspondentes são contatados. Quando não definida, apenas instâncias *.service-now.com são permitidas e hosts internos/loopback são bloqueados (proteção SSRF).
SN_AUTH	não	auto	Método de autenticação: basic, oauth, apikey, token ou none (mTLS somente com certificado). Detectado automaticamente pelas chaves presentes (API key → bearer → OAuth → Basic).
SN_API_KEY	não	—	Chave de API de entrada do ServiceNow, enviada como cabeçalho x-sn-apikey (ativa o modo apikey).
SN_BEARER_TOKEN	não	—	Um token bearer obtido previamente, enviado literalmente como Authorization: Bearer … (ativa o modo token).
SN_OAUTH_CLIENT_ID	não	—	ID do cliente OAuth (sua presença ativa o OAuth).
SN_OAUTH_CLIENT_SECRET	não	—	Segredo do cliente OAuth.
SN_OAUTH_GRANT	não	password	Concessão OAuth: password (obsoleto — ROPC), client_credentials, refresh_token ou jwt_bearer. O comando login define isso como refresh_token para você.
SN_OAUTH_JWT_KEY	não	—	Chave privada PEM para a concessão jwt_bearer (ou SN_OAUTH_JWT_KEY_FILE). Claims opcionais: SN_OAUTH_JWT_ISS (ID do cliente padrão), SN_OAUTH_JWT_SUB (padrão SN_USER), SN_OAUTH_JWT_AUD, SN_OAUTH_JWT_KID, SN_OAUTH_JWT_EXP_SEC (padrão 300).
SN_OAUTH_REFRESH_TOKEN	não	—	Token de atualização para a concessão refresh_token. Obtido automaticamente pelo npx servicenow-mcp-ai login (Authorization Code + PKCE).
SN_OAUTH_REDIRECT_URI	não	http://localhost:53682/callback	URL de redirecionamento de loopback para o fluxo PKCE login. Deve corresponder ao redirecionamento registrado no endpoint OAuth.
SN_OAUTH_SCOPE	não	—	Escopo OAuth opcional solicitado durante login.
SN_TLS_CLIENT_CERT	não	—	Certificado do cliente (PEM) para TLS mútuo (ou SN_TLS_CLIENT_CERT_FILE). Com SN_TLS_CLIENT_KEY apresenta um certificado do cliente; o perfil de autenticação mútua do ServiceNow o mapeia para um usuário. Requer o pacote opcional undici (npm i undici).
SN_TLS_CLIENT_KEY	não	—	Chave privada (PEM) para o certificado do cliente (ou SN_TLS_CLIENT_KEY_FILE).
SN_TLS_CA	não	—	Pacote de CA opcional (PEM) para confiar (ou SN_TLS_CA_FILE). SN_TLS_REJECT_UNAUTHORIZED=false desativa a verificação (não recomendado).
SN_TABLES_ALLOW	não	—	Lista de permissão de tabelas separada por vírgulas; quando definida, apenas essas tabelas são acessíveis.
SN_TABLES_DENY	não	—	Lista de bloqueio de tabelas separada por vírgulas; sempre prevalece sobre a lista de permissão.
SN_READONLY	não	false	Quando verdadeiro, recusa todo create/update/delete.
SN_WRITE_MODE	não	plan	plan (padrão) pré-visualiza uma gravação como diff antes/depois sem mutar; apply executa; passar apply:true força uma única chamada.
SN_REDACT_FIELDS	não	—	DF-5: mascarar estes valores de campo antes que os registros cheguem ao modelo (separados por vírgula/espaço).
SN_REDACT_PII	não	false	DF-5: também mascarar padrões de e-mail/telefone/ID nacional dentro de valores de string.
SN_TRANSPORT	não	stdio	DF-6: stdio (padrão) ou http (Streamable HTTP para clientes remotos/agentes).
SN_PORT	não	3000	DF-6: porta TCP para o transporte http.
SN_HTTP_HOST	não	127.0.0.1	DF-6: endereço de bind para o transporte http (loopback por padrão).
SN_HTTP_TOKEN	não	—	DF-6: quando definido, requisições http devem enviar Authorization: Bearer <token>.
SN_LOG_LEVEL	não	info	Nível de detalhe do log em stderr: error, warn, info, debug.
SN_ENV_FILE	não	—	Caminho explícito para o arquivo de ambiente a ler/gravar.
SN_TOOL_PACKAGES	não	core	Pacotes ou perfis de ferramentas separados por vírgula/espaço para ativar. Perfis: core (padrão) e all. Pacotes: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf. As ferramentas de administração estão sempre ativas. atf executa testes na instância — ative apenas em uma instância não produtiva.
SN_PACKAGES_DENY	não	—	Pacotes separados por vírgula/espaço para excluir mesmo se ativados por SN_TOOL_PACKAGES. A única forma de bloquear APIs de plugins (catalog, change, knowledge…) — a política de tabelas não as enxerga.
SN_PACKAGES_READONLY	não	—	Pacotes separados por vírgula/espaço cujas ferramentas de gravação não são registradas; suas ferramentas de leitura permanecem. Complemento por pacote ao SN_READONLY global.
SN_SCHEMA_CACHE_TTL_SEC	não	300	TTL para o cache de leituras de esquema quase estático (list_tables, describe_table, get_cmdb_meta). 0 desativa o cache.
SN_MAX_CONCURRENT	não	4	Máximo de requisições HTTP paralelas à instância (semáforo simples em processo).
SN_INCLUDE_REF_LINKS	não	false	Campos de referência retornam sem suas URLs link por padrão (economia de tokens). Defina true para incluí-las.
SN_RESULT_PRETTY	não	false	Resultados de ferramentas são JSON compacto por padrão (pretty-printing ~dobra os tokens). Defina true para saída indentada.
SN_DOCS_DIR	não	docs/instance	Diretório em que o pacote docs lê/grava Markdown. Caminhos relativos são resolvidos em relação ao diretório de trabalho.
SN_CODESEARCH	não	false	Opte pela API de Code Search (sn_codesearch) para servicenow_search_code (FT-7). Quando true e o plugin estiver ativo, ela substitui a iteração LIKE; volta para LIKE em qualquer falha.
SN_PROFILE_<NAME>_*	não	—	Perfis de conexão nomeados: SN_PROFILE_DEV_INSTANCE / _USER / _PASSWORD definem o perfil dev. As chaves simples SN_INSTANCE/SN_USER/SN_PASSWORD são o perfil default.
SN_ACTIVE_PROFILE	não	default	Qual perfil as ferramentas usam. Alterne em tempo de execução com servicenow_use_instance (persistido no arquivo de env).

Política de acesso em dois eixos

O acesso é controlado em dois eixos independentes, porque uma restrição de tabela não alcança as APIs baseadas em plugin (Change, Catalog, Knowledge…). Proteja ambos:

Eixo	Habilitar / negar / somente leitura	Exemplo
Tabelas	SN_TABLES_ALLOW / SN_TABLES_DENY / SN_READONLY	SN_TABLES_DENY=change_request bloqueia apenas o caminho da API de Tabela.
Pacotes	SN_TOOL_PACKAGES / SN_PACKAGES_DENY / SN_PACKAGES_READONLY	SN_PACKAGES_DENY=change também bloqueia a API de plugin do Gerenciamento de Mudanças.

Portanto, negar a tabela change_request ainda deixa a API de Gerenciamento de Mudanças (sn_chg_rest) capaz de ler/gravar mudanças — é por isso que o eixo de pacotes existe. Consulte Notas de segurança para o modelo completo (incluindo como a API em lote obedece a ambos os eixos).

Sintaxe de lista: as listas de tabelas (SN_TABLES_ALLOW / SN_TABLES_DENY) são separadas por vírgula; as listas de pacotes (SN_TOOL_PACKAGES, SN_PACKAGES_DENY, SN_PACKAGES_READONLY) aceitam vírgulas ou espaços em branco. Espaços ao redor são removidos em ambas, e a correspondência de tabelas não diferencia maiúsculas de minúsculas — portanto, SN_TABLES_DENY=Change_Request, sys_user funciona.

Executar / depurar

• VS Code: abra a Paleta de Comandos e inicie o servidor definido em .vscode/mcp.json e use-o a partir do Chat.
• MCP Inspector: npm run inspector
• Diretamente: npm start

Interface de linha de comando

O binário publicado servicenow-mcp-ai (execute-o diretamente ou via npx servicenow-mcp-ai) tem três invocações. Todas as configurações de conexão vêm de variáveis de ambiente / do arquivo de ambiente (consulte Variáveis de ambiente); apenas drift aceita argumentos posicionais.

Comando	Parâmetros posicionais	O que faz	Códigos de saída
servicenow-mcp-ai	(nenhum)	Inicia o servidor MCP. O transporte (stdio padrão, ou http) é escolhido por SN_TRANSPORT; executa até SIGINT/SIGTERM.	0 desligamento limpo · 1 erro fatal na inicialização
servicenow-mcp-ai login	(nenhum — opera no perfil ativo)	Login OAuth 2.1 Authorization Code + PKCE único: abre o navegador, captura o redirecionamento de loopback e armazena um token de atualização.	0 sucesso · 1 falha no login
servicenow-mcp-ai drift <profileA> <profileB>	<profileA>, <profileB> — dois nomes de perfis configurados	Gate de drift CI DF-3: compara as duas instâncias e grava um relatório de diferenças em Markdown.	0 sem drift · 1 drift encontrado · 2 uso / erro

login opera no perfil ativo (SN_ACTIVE_PROFILE, padrão default) e lê, para esse perfil:

• SN_INSTANCE — obrigatório; a instância de destino.
• SN_OAUTH_CLIENT_ID — obrigatório; id do cliente de um endpoint OAuth Authorization Code.
• SN_OAUTH_CLIENT_SECRET — opcional; para um cliente confidencial.
• SN_OAUTH_REDIRECT_URI — opcional; URL de loopback, padrão http://localhost:53682/callback. Deve corresponder ao redirecionamento registrado no endpoint.
• SN_OAUTH_SCOPE — opcional; escopo OAuth solicitado.

Ao ter sucesso, ele grava SN_AUTH=oauth, SN_OAUTH_GRANT=refresh_token e SN_OAUTH_REFRESH_TOKEN de volta no arquivo de ambiente (com prefixo de perfil quando o perfil não é default). A URL de autorização é impressa em stderr caso o navegador não abra automaticamente.

drift recebe dois nomes de perfis posicionais; cada um deve resolver para um perfil configurado (SN_PROFILE_<NAME>_*, ou as chaves simples SN_INSTANCE / SN_USER / SN_PASSWORD para default). O relatório em Markdown é escrito em stdout (capture-o como artefato de CI); um resumo de drift de uma linha vai para stderr.

Gate de drift de CI (DF-3)

Compare dois perfis configurados e faça um pipeline falhar em caso de drift de configuração:

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

Desenvolvimento

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 as convenções (um commit por tarefa, testes acompanham a alteração, documentação gerada).

Ferramentas

Esta tabela é gerada a partir dos registros de ferramentas — edite as definições de ferramenta em src/tools/ e execute npm run docs:readme.

Pacote	Ferramenta	Somente leitura	Descrição
table	servicenow_query_table	sim	Lê registros de qualquer tabela do ServiceNow através da Table API
table	servicenow_get_record	sim	Lê um único registro de uma tabela pelo sys_id
table	servicenow_create_record	não	Cria um novo registro em uma tabela com os valores de campo fornecidos
table	servicenow_update_record	não	Atualiza campos de um registro existente identificado pelo sys_id
table	servicenow_delete_record	não	Exclui um registro de uma tabela pelo sys_id
schema	servicenow_list_tables	sim	Lista tabelas de sys_db_object, opcionalmente filtradas por um fragmento de nome ou rótulo
schema	servicenow_describe_table	sim	Lista as colunas de uma tabela (nome, rótulo, tipo, obrigatório, referência) de sys_dictionary
aggregate	servicenow_aggregate	sim	Calcula agregações no servidor (count, avg, min, max, sum) sobre uma tabela via Stats API, com gr… opcional
attachment	servicenow_list_attachments	sim	Lista metadados de anexos, opcionalmente limitados a um registro específico (tabela + sys_id)
attachment	servicenow_get_attachment	sim	Lê os metadados de um único anexo pelo sys_id
attachment	servicenow_download_attachment	sim	Baixa os bytes de um anexo, retornados como base64
attachment	servicenow_upload_attachment	não	Anexa um arquivo (fornecido como base64) a um registro identificado por tabela + sys_id
attachment	servicenow_delete_attachment	não	Exclui um anexo pelo sys_id
importset	servicenow_insert_import_set_row	não	Insere uma única linha em uma tabela de staging e executa seu transform map
importset	servicenow_get_import_set_row	sim	Lê o resultado do transform para uma linha de staging previamente inserida pelo sys_id
batch	servicenow_batch	não	Executa várias sub-solicitações REST do ServiceNow em uma única ida e volta HTTP via Batch API
catalog	servicenow_list_catalogs	sim	Lista os Service Catalogs disponíveis na instância (Service Catalog API)
catalog	servicenow_list_catalog_categories	sim	Lista as categorias dentro de um service catalog
catalog	servicenow_list_catalog_items	sim	Busca/lista itens de catálogo ordenáveis, opcionalmente por texto ou categoria
catalog	servicenow_get_catalog_item	sim	Obtém um item de catálogo, incluindo suas variáveis de pedido, pelo sys_id
catalog	servicenow_order_catalog_item	não	Faz o pedido de um item de catálogo diretamente ('order now')
change	servicenow_list_changes	sim	Lista change requests através da Change Management API
change	servicenow_get_change	sim	Obtém um único change request pelo sys_id
change	servicenow_create_change	não	Cria uma mudança normal, padrão ou de emergência
change	servicenow_update_change	não	Atualiza campos de um change request pelo sys_id
change	servicenow_change_conflicts	não	Lê conflitos de agendamento de uma mudança, ou os recalcula (calculate=true)
knowledge	servicenow_search_knowledge	sim	Busca em texto completo de artigos de conhecimento (Knowledge API), com query codificada e paginação opcionais
knowledge	servicenow_get_knowledge_article	sim	Obtém um artigo de conhecimento (conteúdo e metadados) pelo sys_id
knowledge	servicenow_knowledge_highlights	sim	Lista artigos de conhecimento em destaque ou mais visualizados para o usuário atual
cmdb	servicenow_list_cis	sim	Lista itens de configuração de uma classe CMDB através da CMDB Instance API com reconhecimento de classe
cmdb	servicenow_get_ci	sim	Obtém um CI com seus atributos e relações de entrada/saída pela classe e sys_id
cmdb	servicenow_create_ci	não	Cria um CI via CMDB Instance API (roteado através de Identification & Reconciliation)
cmdb	servicenow_update_ci	não	Atualiza os atributos de um CI via CMDB Instance API (IRE)
cmdb	servicenow_get_cmdb_meta	sim	Obtém o schema/metadados de uma classe CMDB (atributos, regras de relacionamento) da CMDB Meta API
scripts	servicenow_list_scripts	sim	Lista artefatos de script de um tipo como metadados compactos (sem código-fonte)
scripts	servicenow_get_script	sim	Lê um artefato de script completo, incluindo seu código-fonte e contexto de execução
scripts	servicenow_search_code	sim	Busca uma substring literal no código-fonte de scripts em um ou todos os tipos de script
scripts	servicenow_table_logic	sim	Monta a automação que executa em uma tabela: business rules (ordenadas por when+order), client scripts, UI po…
scripts	servicenow_where_used	sim	Encontra onde uma tabela, campo ou script é referenciado no código da instância: referências textuais em cada s…
flows	servicenow_trace_table_event	sim	Rastreia deterministicamente o que o ServiceNow executaria para uma operação de tabela, em ordem de execução: display/before…
flows	servicenow_list_flows	sim	Lista Flow Designer flows (sys_hub_flow) ou workflows legados (kind: 'workflow') como metadados compactos
flows	servicenow_get_flow	sim	Obtém uma visão estruturada de um flow ou workflow: seu gatilho (tabela/condição/quando) e passos ordenados
flows	servicenow_get_flow_runs	sim	Lê evidências de execução de flow de sys_flow_context — pelo sys_id do flow ou pelo registro (documento) em que exe…
codecheck	servicenow_lint_script	sim	Executa regras determinísticas de qualidade de código sobre um artefato de script (sys_ids/URLs codificados, loops ilimitados ou em l…
codecheck	servicenow_lint_table	sim	Faz lint de toda business rule, client script e UI policy ativos de uma tabela (via table_logic), retornando por sc…
codecheck	servicenow_code_health	não	Agrega a visão geral de saúde do código: contagens de scripts por tipo, uma varredura de segurança da camada de controle de acesso (ACL scri…
docs	servicenow_docs_list	sim	Lista os documentos Markdown na pasta local de documentação da instância (SN_DOCS_DIR)
docs	servicenow_docs_read	sim	Lê um documento Markdown da pasta local de documentação da instância
docs	servicenow_docs_search	sim	Busca na documentação local da instância por uma substring; retorna um trecho por correspondência
docs	servicenow_docs_write	não	Cria ou sobrescreve um documento Markdown na pasta local de docs e atualiza o index.md
docs	servicenow_generate_er_diagram	sim	Constrói um erDiagram Mermaid a partir de sys_dictionary: uma entidade por tabela mais um relacionamento para cada referência…
docs	servicenow_generate_table_flow	sim	Constrói um fluxograma Mermaid do ciclo de vida de um registro em uma tabela, agrupando business rules ativas por fase (disp…
instance	servicenow_snapshot_instance	não	Baixa os metadados estruturais da instância para a pasta local de docs (SN_DOCS_DIR//): tables.md+…
instance	servicenow_compare_instances	não	Compara dois perfis de conexão: tabelas presentes em apenas um, colunas comuns cujo tipo/obrigatório/referência difer…
email	servicenow_send_email	não	Envia um e-mail através da Email API da instância, opcionalmente associado a um registro (tabela + sys_id)
email	servicenow_get_email	sim	Lê um registro de e-mail enviado/recebido pelo sys_id (Email API)
atf	servicenow_list_atf_tests	sim	Lista testes do Automated Test Framework (sys_atf_test) como metadados: nome, flag ativo, descrição
atf	servicenow_list_atf_suites	sim	Lista suítes de teste do Automated Test Framework (sys_atf_test_suite) como metadados
atf	servicenow_run_atf_test	não	Executa um único teste ATF através da CI/CD API
atf	servicenow_run_atf_suite	não	Executa uma suíte de testes ATF através da CI/CD API
atf	servicenow_get_atf_result	sim	Consulta uma execução ATF pelo seu execution id: status, percentual concluído e mensagem (CI/CD progress API)
admin	servicenow_set_credentials	não	Salva ou atualiza as credenciais de conexão do ServiceNow
admin	servicenow_list_instances	sim	Lista os perfis de conexão ServiceNow configurados (instâncias): nome, host, usuário, flag de somente leitura e se…
admin	servicenow_use_instance	não	Alterna o perfil de conexão ServiceNow ativo (persistido no arquivo de ambiente)
admin	servicenow_get_status	sim	Mostra a instância configurada, usuário, modo de autenticação e política de acesso, e se as credenciais estão completas
admin	servicenow_test_connection	sim	Verifica se as credenciais configuradas realmente funcionam: lê um registro sys_user e reporta ok/status/latency
admin	servicenow_check_capabilities	sim	Pré-valida quais tabelas sys_* restritas a administradores o usuário conectado pode realmente ler, e reporta quais níveis super…

Todas as ferramentas carregam anotações MCP (readOnlyHint, destructiveHint, idempotentHint) para que os clientes possam aplicar a UX de confirmação adequada.

Pacotes de ferramentas

As ferramentas são agrupadas em pacotes para que você possa expor apenas o que um determinado cliente precisa (menos ferramentas mantêm o modelo focado). Defina SN_TOOL_PACKAGES como uma lista separada por vírgula/espaço de perfis ou nomes de pacotes:

• core (padrão) — table, schema, aggregate, attachment.
• all — todos os pacotes abaixo.
• Pacotes individuais: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf.

As ferramentas administrativas (servicenow_set_credentials, servicenow_get_status) são sempre registradas, independentemente dos pacotes ativos. Nomes desconhecidos são ignorados. servicenow_get_status relata a resolução de enabledPackages.

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

Presets

Se você preferir não cuidar da lista manualmente, três presets nomeados cobrem os papéis comuns. As ferramentas administrativas estão sempre ativas, portanto não estão listadas. Cada preset também tem um alias de uma palavra — SN_TOOL_PACKAGES=reader|developer|admin — que expande para o mesmo conjunto de pacotes.

Preset	SN_TOOL_PACKAGES=…	Para quem
reader	table,schema,aggregate	Primeiro contato, analistas, um laboratório PDI — apenas leitura e consulta.
developer	table,schema,aggregate,scripts,flows,codecheck,docs	O segmento principal: inteligência de script, rastreamento de flows, linting, docs e diagramas.
admin	all	Tudo, incluindo o plugin e os pacotes com muitas operações de escrita.

O preset developer se baseia no conjunto reader; o pacote docs inclui os geradores de diagramas Mermaid. Use o alias por brevidade ou escreva os pacotes por extenso para adicionar ou remover um.

Exemplos

Consulte os 5 incidentes ativos mais recentes:

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

Crie um incidente:

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

Atualize credenciais em tempo de execução:

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

Recursos

Metadados somente leitura também são expostos como recursos MCP, para que os clientes possam anexá-los declarativamente em vez de chamar uma ferramenta:

URI	Descrição
servicenow://status	Status da conexão, modo de autenticação, política de acesso.
servicenow://tables	Lista de tabelas de sys_db_object.
servicenow://schema/{table}	Colunas de uma tabela de sys_dictionary.
servicenow://docs/{path}	Um documento Markdown da loja local de docs.

Prompts

Workflows prontos são expostos como prompts MCP; eles orquestram as ferramentas e insistem em ler valores reais da instância:

Prompt	Argumento	Finalidade
servicenow_incident_triage	incident	Resumir, avaliar prioridade, categorizar e recomendar próximos passos.
servicenow_change_impact_analysis	change	CIs afetados, conflitos de agenda e uma decisão de prosseguir ou não.
servicenow_document_table	table	Esquema + automação + diagramas → documento Markdown salvo.

Estrutura do projeto

.
├── .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 nomes: o pacote npm e o repositório GitHub são ambos servicenow-mcp-ai (o servicenow-mcp sem escopo já estava ocupado no npm); a pasta de trabalho local é servicenow-mcp. A diferença é cosmética e não afeta a compilação ou o tempo de execução.

Notas de segurança

• O arquivo env é ignorado pelo git — não faça commit de credenciais reais.
• O arquivo env é gravado somente para o proprietário (0600) — ele contém uma senha em texto puro.
• O servidor usa o transporte stdio e registra logs apenas em stderr; segredos e consultas codificadas brutas nunca são registrados.
• A senha/token nunca é retornada por nenhuma ferramenta.
• Os hosts são restritos: sem SN_ALLOWED_HOSTS, apenas instâncias *.service-now.com são contatadas (interno/loopback sempre bloqueados), portanto um host redirecionado ou digitado incorretamente não pode receber credenciais silenciosamente. Defina SN_ALLOWED_HOSTS para optar por um domínio personalizado ou de nuvem soberana.
• Prefira OAuth 2.0 em vez de Basic quando possível (SN_OAUTH_CLIENT_ID).
• Aplique privilégio mínimo com SN_TABLES_ALLOW / SN_TABLES_DENY e SN_READONLY=true para implantações somente leitura.
• A política de tabelas não cobre APIs de plugins. SN_TABLES_DENY=change_request bloqueia o caminho da Table API, mas a API de Change Management (sn_chg_rest) ainda pode ler/gravar mudanças. Para restringir as superfícies baseadas em plugins, use SN_PACKAGES_DENY (remova o pacote inteiro) ou SN_PACKAGES_READONLY (registre apenas suas ferramentas de leitura). A Batch API também obedece a ambos os eixos: uma sub-requisição para o caminho de um pacote negado é recusada, e gravações em um pacote somente leitura são bloqueadas — um lote não pode ser usado para contornar a política de pacotes.

Documentação do projeto

Documento	Conteúdo
ARCHITECTURE.md	Arquitetura em camadas, diagramas Mermaid (módulos, ciclo de vida de requisições, modelo de segurança, autenticação, pacotes), ADRs condensados
PRODUCT-STATE.md	Estado atual do produto: mapa de cobertura da API, status de qualidade, linha do tempo do histórico, roadmap
ROADMAP.md	Plano futuro: lançar 1.0.0, Fase 8 (testes de fluxo + análise de código), Fase 9 (diferenciais competitivos), itens opcionais e adiados
COMPETITIVE-ANALYSIS.md	Posicionamento vs o ServiceNow MCP Server Console oficial: comparação, onde fica estruturalmente atrás, o plano de impulso da Fase 9 e riscos de plataforma
IMPLEMENTATION-PLAN.md	Especificações detalhadas para as próximas fases (harness 2.0, multi-instância, testes de fluxo)
DONE.md / TODO.md	Trabalho concluído com referências de commit / decisões restantes
WORKLOG.md / CHANGELOG.md	Diário de trabalho detalhado / changelog voltado ao usuário
CONTRIBUTING.md / SECURITY.md	Configuração de desenvolvimento, portões e convenções / modelo de segurança e relatórios

Suporte

Este projeto é construído e mantido no meu próprio tempo. Se ele economiza tempo para você ou sua equipe, considere apoiar seu desenvolvimento contínuo — o patrocínio financia diretamente novas ferramentas, correções de bugs e a manutenção do ritmo com a superfície REST do ServiceNow.

• GitHub Sponsors — doação única ou recorrente, sem taxa de plataforma (a opção preferida).
• Ko-fi — suporte rápido de doação única; também aceita PayPal, sendo a opção alternativa para quem não tem conta no GitHub.
• Donate (Donatree) — uma página de doação sem conta (cartão, PayPal e mais) para uma contribuição única.

Marca registrada

servicenow-mcp-ai é um projeto independente, construído pela comunidade. Ele não é afiliado, endossado ou patrocinado pela ServiceNow, Inc.

"ServiceNow", o logotipo da ServiceNow, "Now" e marcas relacionadas são marcas comerciais ou marcas registradas da ServiceNow, Inc. nos Estados Unidos e em outros países. Elas são usadas no nome e na documentação deste projeto apenas de forma nominativa — para identificar a plataforma com a qual este software interopera — e nenhuma afiliação ou endosso está implícito. Todos os outros nomes de produtos e marcas são propriedade de seus respectivos proprietários.

Este projeto é licenciado sob a MIT License; essa licença cobre o código-fonte e não concede nenhum direito de uso das marcas comerciais da ServiceNow.