ServiceNow MCP

servicenow-mcp-ai — Servidor MCP ServiceNow

📖 Site de documentação →

Um servidor Model Context Protocol que permite a um cliente MCP (VS Code, Claude Desktop, etc.) executar 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 do Service Catalog, Change Management e Knowledge. As credenciais são mantidas em um arquivo env local e podem ser atualizadas em tempo de execução por meio de uma ferramenta.

Atualizando da versão 1.x? A v2.0 torna as gravações planejadas por padrão: create/update/delete e as outras ferramentas de gravação de registros retornam uma prévia não mutável, a menos que você passe apply: true (ou defina SN_WRITE_MODE=apply para restaurar o comportamento "executar imediatamente" da v1). Consulte o CHANGELOG → 2.0.0 para a nota completa de migração.

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 for útil, uma doação no GitHub Sponsors ajuda a manter o projeto. As opções completas de Suporte estão no final.

Demonstração rápida

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

1. "Onde este campo é realmente usado?" — todos os scripts, regras de negócio, scripts de cliente, políticas/ações de UI e ACLs que o utilizam, como JSON ou um gráfico Mermaid. A busca find usages com qualidade de IDE que o ServiceNow não tem botão para:

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

2. "O que é executado quando salvo este registro?" — a cadeia completa de automação em ordem de execução (regras de negócio display → before → after → assíncronas, depois flows, 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 mudou entre dev e prod?" — um diff em Markdown de tabelas, colunas, scripts (correspondidos por sys_id e depois nome, com um diff unificado de cada script alterado) e plugins entre dois perfis configurados — além, sob solicitação, de propriedades, choices, ACLs, notificações, flows, itens de catálogo e papéis — 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

Todos os 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 extras do ServiceNow: Aggregate (Stats), Attachment (listar/enviar/baixar/excluir), Import Set, Batch (várias chamadas REST em uma ú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 conhecimento de classe + meta, leituras de relacionamento de cmdb_rel_ci, IRE identify-and-reconcile com um plano somente de identificação), Service Catalog (navegar/ordenar itens), Change Management (criação tipada + detecção de conflitos) e Knowledge (busca de artigos). APIs com escopo de plugin relatam claramente quando não estão ativas na instância.
• Inteligência de scripts: ler e pesquisar o código da própria instância (regras de negócio, script includes, scripts de cliente, políticas/ações de UI, jobs agendados, scripts de transform/REST, ACLs — e, ainda não verificado em uma instância ativa, widgets do Service Portal, páginas/scripts/macros de UI, processadores, scripts de email/fix/validação, ações de script, fontes de dados, funções de mensagem REST, mapas/entradas de transform, scripts de cliente de catálogo e cálculos/padrões de dicionário) e obter o panorama completo de automação de uma tabela — tudo somente leitura pela API Table. servicenow_search_code retorna cada linha correspondente por artefato (até 20, com uma linha de contexto em cada lado) e, como servicenow_where_used, aceita um scope de aplicação opcional. servicenow_where_used também encontra referências estruturais — campos de referência de dicionário, layouts de lista e formulário, variáveis de catálogo, entradas de fluxo e relatórios — em uma seção separada de structural.
• Rastreamento de fluxos e verificação de código (Fase 8): rastrear deterministicamente o que uma operação de tabela executa (pacote flows — regras de negócio, flows, workflows e notificações, em ordem, com um fluxograma Mermaid), ler flows do Flow Designer e histórico de execução, e fazer lint de scripts contra um conjunto de regras local com um relatório agregado de saúde de código (codecheck). Executar testes ATF via API CI/CD (atf, opt-in, não padrão — as ferramentas de execução operam na instância).
• Desfazer baseado em diário (revert): listar o diário local de gravações e reverter um create/update/delete aplicado — com uma verificação de divergência contra edições posteriores.
• Leituras genéricas de artefatos (artifacts, opt-in): listar e ler qualquer tipo de artefato registrado — políticas de UI com suas ações, páginas de portal com seu layout, flows, itens de catálogo e mais — com escopo e status gerenciado por SDK.
• Consciência de update sets (updatesets, opt-in): listar update sets, resumir um conjunto por artefato, compará-lo com outro perfil ou um snapshot — e vincular gravações de Table aplicadas a um update set nomeado (update_set / SN_UPDATE_SET), restaurando o conjunto atual do usuário depois.
• Operações e saúde de dados (ops, opt-in): leituras limitadas de "por que está lento" do log do sistema, da fila do agendador, da fila de email de saída e semáforos, além de servicenow_data_health — chaves duplicadas, referências órfãs e desatualizadas para uma tabela, a partir de contagens da API Aggregate.
• Leituras de operações (opt-in): o histórico de alterações de um registro de sys_audit e sys_journal_field (history — incluindo os comentários e work notes que a API Table lê vazios), propriedades do sistema com segredos mascarados e um conjunto registrado e reversível (properties), e consultas de usuário / grupo / papel com associações (directory). Execuções ATF podem aguardar seu resultado (wait_seconds), e inserções de Import Set relatam a execução de transform e mapas.
• Autodocumentação: uma base de conhecimento local em Markdown (ler/gravar/pesquisar) além de geradores determinísticos de Mermaid (diagramas ER a partir de referências, fluxogramas de ciclo de vida de registros 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ças, documentar uma tabela, diagnosticar uma instância lenta) 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 Básica ou OAuth 2.0 sobre HTTPS; a senha/token nunca é ecoada de volta.
• Controles de privilégio mínimo: listas de permitir/negar de tabelas e um modo global somente leitura.
• Resiliência: timeout por solicitação, nova tentativa com backoff e Retry-After, proteção contra SSRF e um limite de tamanho de resultado.
• Anotações de ferramentas e recursos MCP, payloads de erro estruturados e registro estruturado em stderr.
• Credenciais em um arquivo env (projeto, ~/.config ou SN_ENV_FILE), atualizáveis em tempo de execução via servicenow_set_credentials.

Requisitos

• Node.js 20+ (imposto: engines + uma proteção em 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

Instalar no seu cliente MCP

Cada cliente inicia o mesmo comando stdio, npx -y servicenow-mcp-ai (Node.js 20+), sob o nome de servidor servicenow. Os links de um clique e trechos abaixo não carregam credenciais: mantenha-as no arquivo env (~/.config/servicenow-mcp-ai/.env, consulte Configurar credenciais), execute o npx servicenow-mcp-ai login único para OAuth, ou peça ao assistente para chamar servicenow_set_credentials assim que o servidor estiver conectado. Uma variável de ambiente real definida em uma configuração de cliente substitui o arquivo env, então só adicione um bloco env quando realmente necessário — e nunca coloque SN_PASSWORD ou outros segredos em uma configuração de cliente que você compartilhe ou faça commit (consulte SECURITY.md).

code --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'
code-insiders --add-mcp '{"name":"servicenow","command":"npx","args":["-y","servicenow-mcp-ai"]}'

vscode:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D
vscode-insiders:mcp/install?%7B%22name%22%3A%22servicenow%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22servicenow-mcp-ai%22%5D%7D

{
  "servers": {
    "servicenow": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}

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

claude mcp add servicenow --scope user --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai

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

cursor://anysphere.cursor-deeplink/mcp/install?name=servicenow&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNlcnZpY2Vub3ctbWNwLWFpIl19

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

{
  "context_servers": {
    "servicenow": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"],
      "env": {}
    }
  }
}

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

codex mcp add servicenow --env SN_INSTANCE=your-instance.service-now.com -- npx -y servicenow-mcp-ai

[mcp_servers.servicenow]
command = "npx"
args = ["-y", "servicenow-mcp-ai"]
# Optional, non-secret only — secrets stay in ~/.config/servicenow-mcp-ai/.env:
# env = { SN_INSTANCE = "your-instance.service-now.com" }

Prefere uma instalação global (npm install -g servicenow-mcp-ai)? Substitua "command": "npx", "args": ["-y", "servicenow-mcp-ai"] por "command": "servicenow-mcp-ai" em qualquer trecho. O MCP Inspector funciona da mesma forma: npx @modelcontextprotocol/inspector npx -y servicenow-mcp-ai.

Os links de um clique são gerados a partir de package.json por scripts/install-links.mjs (node scripts/install-links.mjs os imprime); test/install-links.test.js falha se este README ou o site de documentação divergirem das strings geradas.

Início rápido

O caminho mais rápido são 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 Environment variables para o restante.

Além de um teste rápido, prefira OAuth a uma 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 Configure credentials → OAuth 2.1.

Verifique sua configuração

Depois 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 relata ok, status HTTP e latência.
2. Execute servicenow_check_capabilities — ela pré-visualiza quais tabelas sys_* restritas a administradores o usuário conectado pode realmente ler.

Ou faça ambos pelo shell de uma só vez:

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

Prefere ser perguntado? npx servicenow-mcp-ai init solicita a instância, o método de autenticação e as credenciais, grava o arquivo de ambiente e executa doctor — consulte Command-line interface.

Configure credentials

As credenciais ficam 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 defini-las ou alterá-las em tempo de execução chamando a ferramenta servicenow_set_credentials — os novos valores são gravados diretamente de volta no arquivo de ambiente. Mover um perfil configurado para uma instância diferente exige user e password na mesma chamada (os segredos armazenados nunca são enviados para outro host), e a alteração deve ser confirmada pelo cliente — clientes sem suporte a elicitação são recusados, a menos que SN_ALLOW_UNCONFIRMED_CREDENTIAL_CHANGE=1 esteja definido.

A ferramenta também define o método de autenticação (auth), o ID do cliente OAuth (oauth_client_id) e a concessão (oauth_grant). Segredos — a chave de API e o segredo do cliente OAuth — nunca são argumentos de ferramenta: liste-os em request_secrets e o servidor os solicita por meio de um prompt de elicitação, para que nunca apareçam em uma chamada de ferramenta registrada, no resultado ou no diário de gravação. Um cliente sem suporte a elicitação é recusado (a opção de exclusão acima não se aplica a segredos); defina essas chaves no arquivo de ambiente em vez disso. A regra de alteração de instância segue o método de autenticação resultante: um perfil com chave de API precisa de uma nova chave de API, um perfil OAuth client_credentials de um novo segredo de cliente, a concessão OAuth password de usuário, senha e segredo de cliente; Basic / none de usuário e senha; perfis de bearer token, refresh_token e jwt_bearer não podem ser movidos com esta ferramenta.

servicenow_get_status (authWarnings), servicenow_list_instances e doctor avaliam cada perfil em relação ao seu próprio método de autenticação — um perfil com chave de API não precisa de senha — e relatam o método, a concessão OAuth, o estado do refresh token e o modo de gravação, nunca um valor secreto. Quando a concessão de refresh token retorna um refresh token rotacionado, ele é gravado de volta na chave de ambiente da qual foi lido; se o arquivo de ambiente não puder ser gravado, o novo token é mantido em memória (perdido na reinicialização) e um aviso é registrado e exibido por get_status / doctor. Valores que o servidor grava mantêm caminhos do Windows literais (barras invertidas são entre aspas simples) e um arquivo de ambiente CRLF permanece CRLF. No Windows, o arquivo de ambiente herda a ACL de sua pasta — restrinja você mesmo (por exemplo, icacls .env /inheritance:r /grant:r "%USERNAME%:F"); o servidor apenas avisa, nunca executa icacls.

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

Primeira execução: o modelo se configura sozinho

Em initialize, o servidor envia instructions construído a partir da configuração ativa: os pacotes habilitados e a contagem de ferramentas, o modo de gravação, o perfil ativo e, quando nada está configurado, o que está faltando e como corrigir. Até então, toda ferramenta de instância falha com error.code: "NOT_CONFIGURED" e uma dica nomeando servicenow_set_credentials. Uma primeira sessão com um arquivo de ambiente vazio se parece com isto (abreviado):

instructions  Credentials: NOT configured (missing instance, user, password). Instance tools
              fail with error.code NOT_CONFIGURED until fixed. To configure: ask the user for
              the instance and credentials, call servicenow_set_credentials, then
              servicenow_test_connection. Never guess or echo a password.
user          How many open P1 incidents do we have?
model         Which instance, user and password should I connect with?
user          dev12345, admin, ••••••
tool call     servicenow_set_credentials { instance: "dev12345", user: "admin", password: … }
tool result   { message: "Credentials saved", profile: "default", configured: true, password: "***" }
tool call     servicenow_test_connection {}
tool result   { ok: true, … }
tool call     servicenow_aggregate { table: "incident", query: "active=true^priority=1" }
model         There are 7 open P1 incidents.

servicenow_get_status então mostra o estado ativo: versão do servidor, tempo de atividade e transporte, policy.summary, limites, redação, o diretório de documentação, contadores de gravação, a fonte do perfil e profileDetails (modo de autenticação por perfil, modo de gravação e chaves ausentes) — nunca um valor secreto.

OAuth 2.1 (Authorization Code + PKCE) — recomendado

Registre um endpoint de API OAuth Authorization Code no ServiceNow com uma URL de redirecionamento de loopback (por exemplo, http://localhost:53682/callback), defina SN_OAUTH_CLIENT_ID (e SN_OAUTH_CLIENT_SECRET para um cliente confidencial), então 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 OAuth 2.0 (ROPC) 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. Consulte .env.example.

Métodos de autenticação suportados

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

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. Consulte .env.example para um modelo.

| SN_DESTRUCTIVE_CONFIRM | não | off | H-3: confirmação para uma apply:true destrutiva (delete_record, delete_attachment, uma batch de escrita, send_email, order_catalog_item, revert_write, change_conflicts com calculate:true) no modo de plano. token: a pré-visualização do plano retorna um plan_token de uso único e a aplicação deve devolvê-lo com os mesmos argumentos, caso contrário PLAN_REQUIRED; elicit: token mais um prompt de confirmação em clientes com elicitação (uma recusa é CONFIRM_DECLINED, registrada como recusada). SN_WRITE_MODE=apply ignora isso, exceto em um perfil marcado como prod (SN_ENV), que é sempre pelo menos elicit e é confirmado também no modo de aplicação. O padrão 3.0 é uma decisão do proprietário (O-4). | | SN_PLAN_TOKEN_TTL_SEC | não | 600 | H-3: tempo de vida de um plan_token em segundos (30–86400). Os tokens vivem apenas no processo do servidor e são consumidos pela aplicação. | | SN_BATCH_UNMAPPED | não | allow | H-4: uma sub-solicitação servicenow_batch cujo caminho REST não pertence a nenhum pacote de ferramentas: allow verifica-o apenas contra a tabela e os eixos somente leitura; deny recusa-o (portanto, uma nova API de plugin não pode passar SN_PACKAGES_DENY / SN_PACKAGES_READONLY dentro de um lote). Um lote aninhado é sempre recusado. O padrão 3.0 é uma decisão do proprietário (O-4). | | SN_BATCH_MAX_REQUESTS | não | 1000 | H-4: número máximo de sub-solicitações que uma chamada servicenow_batch pode carregar (1–1000), verificado antes de qualquer envio. | | SN_PROTECTED_TABLES_WRITE | não | allow | H-11: deny recusa gravações nas tabelas protegidas integradas (identidade, papéis, ACLs, sys_properties, OAuth, scripts, LDAP, certificados, fontes de dados, mensagens REST — servicenow_explain_policy as lista) com POLICY_DENIED; uma entrada exata de SN_TABLES_ALLOW reabilita uma. Leituras não são afetadas. O padrão 3.0 é uma decisão do proprietário (O-4). Por perfil: SN_PROFILE_<NAME>_PROTECTED_TABLES_WRITE. | | SN_IMPORT_SET_TABLES | não | — | H-11: padrões (*, ?) que a tabela de staging do import-set deve corresponder (ex.: u_*,imp_*); não definido = qualquer tabela que a política de tabelas permitir. | | SN_MAX_WRITES_PER_SESSION | não | — | H-11: número máximo de gravações aplicadas por sessão (o processo em stdio, uma sessão MCP sobre HTTP; um lote conta suas sub-solicitações de escrita). Além disso, as gravações falham com WRITE_CAP antes de qualquer solicitação; get_status.writes.caps mostra o uso. Não definido = sem limite. | | SN_MAX_DELETES_PER_SESSION | não | — | H-11: número máximo de exclusões aplicadas por sessão (WRITE_CAP). Não definido = sem limite. | | SN_MAX_BATCH_WRITES | não | — | H-11: número máximo de sub-solicitações de escrita (não-GET) em um servicenow_batch (WRITE_CAP). Não definido = sem limite. | | SN_ENV | não | — | H-11: marca o perfil padrão como prod, test ou dev (SN_PROFILE_<NAME>_ENV para outros). Um perfil prod permanece no modo de plano mesmo quando a aplicação está configurada, a menos que SN_PROD_WRITES (SN_PROFILE_<NAME>_PROD_WRITES) seja I_UNDERSTAND; suas aplicações destrutivas são sempre confirmadas (pelo menos SN_DESTRUCTIVE_CONFIRM=elicit, também no modo de aplicação — CONFIRM_REQUIRED para um cliente sem elicitação); os resultados carregam _meta.environment; use_instance avisa. SN_PROFILE_<NAME>_WRITE_MODE define o modo de escrita por perfil. | | SN_PROD_WRITES | não | — | H-11: I_UNDERSTAND permite que um perfil padrão prod execute no modo de aplicação. | | SN_UPDATE_SET | não | — | S-6: conjunto de atualização (sys_id ou nome exato) no qual as gravações de ferramentas de Tabela aplicadas (criar / atualizar / upsert / excluir) são registradas; um update_set por chamada o substitui e SN_PROFILE_<NAME>_UPDATE_SET o define por perfil. O plano nomeia o conjunto; o conjunto de atualização atual do usuário é trocado para a gravação e restaurado após ela. Tabelas de linhas de dados são gravadas inalteradas. | | SN_EMAIL_ALLOWED_DOMAINS | não | — | Domínios de destinatários que servicenow_send_email pode endereçar (para/cc/bcc; um domínio cobre seus subdomínios, * permite qualquer). Quando não definido, todo destinatário deve ser o e-mail de um usuário na tabela sys_user da própria instância; qualquer outra coisa falha com RECIPIENT_NOT_ALLOWED. | | SN_MAX_UPLOAD_BYTES | não | 10485760 | Maior anexo de upload decodificado, verificado no comprimento base64 antes da decodificação (PAYLOAD_TOO_LARGE). | | SN_UPLOAD_MIME_ALLOW | não | — | Lista de permissões opcional de tipos de conteúdo de upload (exatos, ou type/*); outros falham com MIME_NOT_ALLOWED. | | SN_REDACT_FIELDS | não | — | DF-5: mascarar esses 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. Desde H-5, ambas as configurações de redação se aplicam profundamente a todo resultado de ferramenta (sucesso e erro) e ao diário de gravação. | | SN_JOURNAL_MAX_BYTES | não | 20971520 | H-5: tamanho (bytes, padrão 20 MiB) no qual write-journal.jsonl rotaciona para write-journal.<ISO-time>.jsonl; a cadeia de hash continua entre arquivos. | | SN_CSV_FORMULA_GUARD | não | true | H-5: prefixar células de texto CSV que começam com =, +, -, @, tabulação ou CR com ' para que planilhas nunca as avaliem (um -5 de texto exporta como '-5). 0 opta por não participar. | | SN_CSV_BOM | não | true | H-5: antepor um BOM UTF-8 às exportações format:"csv" para que o Excel decodifique texto não-ASCII. 0 opta por não participar. | | SN_TRANSPORT | não | stdio | DF-6: stdio (padrão) ou http (HTTP Streamable 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, solicitações http devem enviar Authorization: Bearer <token>. | | SN_LOG_LEVEL | não | info | Verbosidade de log no stderr: error, warn, info, debug. | | SN_LOG_FORMAT | não | json | E-5: formato de linha de log no stderr — json (um objeto por linha) ou text (HH:MM:SS level message key=value). | | SN_LOG_FILE | não | — | E-5: também anexar toda linha de log (JSON Lines, redigido, modo 0600) a este arquivo, com rotação baseada em tamanho (<file>.1 … <file>.5). O stderr continua funcionando. | | SN_LOG_FILE_MAX_BYTES | não | 10485760 | E-5: limite de rotação para SN_LOG_FILE (bytes). | | SN_METRICS | não | off | E-5: somente transporte HTTP — servir métricas Prometheus em GET /metrics, atrás de SN_HTTP_TOKEN (desabilitado quando nenhum token é definido). | | SN_EXPERIMENTAL_TASKS | não | 0 | M-9, experimental: 1 adiciona um argumento opcional run_as_task:true a snapshot_instance, compare_instances, run_atf_test, run_atf_suite, code_health e query_table (somente format:"file"). Tal chamada retorna um identificador de tarefa MCP imediatamente (_meta["io.modelcontextprotocol/related-task"]); o cliente consulta tasks/get, lê tasks/result (mantido por 1 h, redigido) ou o interrompe com tasks/cancel. Desligado: esquemas inalterados. Construído na API de tarefas experimental do SDK. | | SN_LOG_NOTIFY_RATE | não | 20 | M-8: notificações de log por segundo e sessão de cliente sobre a capacidade de log do MCP (rajada 50, ou a taxa se maior). Linhas acima disso são contadas e relatadas em um aviso "N mensagens de log suprimidas" por minuto; stderr nunca é limitado. 0 = sem limite. | | SN_ENV_FILE | não | — | Caminho explícito para o arquivo de ambiente a ser lido/gravado. | | SN_TOOL_PACKAGES | não | core | Pacotes de ferramentas ou perfis separados por vírgula/espaço para habilitar. Perfis: core (padrão), all e os predefinidos reader | developer | admin (veja Predefinições). Pacotes: table, schema, aggregate, attachment, importset, batch, catalog, change, knowledge, cmdb, scripts, flows, codecheck, docs, instance, email, atf, revert, artifacts, updatesets, ops, history, properties, directory, ui. As ferramentas de administração estão sempre ativas. atf executa testes na instância — habilite-o apenas em uma instância não-produtiva. | | SN_PACKAGES_DENY | não | — | Pacotes separados por vírgula/espaço para excluir mesmo se habilitados por SN_TOOL_PACKAGES. A única maneira de bloquear APIs de plugin (catálogo, mudança, conhecimento…) — a política de tabelas não as vê. | | SN_PACKAGES_READONLY | não | — | Pacotes separados por vírgula/espaço cujas ferramentas de escrita 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 desabilita o cache. | | SN_SCHEMA_CACHE_MAX | não | 256 | Número máximo de entradas no cache de leituras de esquema; quando cheio, a entrada menos recentemente usada é removida. Contadores (size, hits, misses, evictions) aparecem em get_status sob schemaCache. | | SN_CAPABILITY_TTL_MS | não | 600000 | Por quanto tempo uma sonda de capacidade bem-sucedida é armazenada em cache — a matriz servicenow_check_capabilities e a disponibilidade da API de plugin (CI/CD, Code Search, Batch…). Passe refresh: true para re-sondar mais cedo. | | SN_PLUGIN_NEGATIVE_TTL_MS | não | 60000 | Por quanto tempo uma sonda de capacidade falha (HTTP 401/403/404/5xx) ou uma API de plugin ausente é armazenada em cache antes de ser tentada novamente. Erros de transporte nunca são armazenados em cache. | | SN_MAX_CONCURRENT | não | 4 | Número máximo de solicitações HTTP paralelas à instância (semáforo simples em processo). | | SN_MAX_QUEUE | não | 64 | Número máximo de solicitações aguardando por host para um slot livre além de SN_MAX_CONCURRENT. Estouro falha imediatamente com código BUSY em vez de acumular. Diagnósticos (servicenow_test_connection, doctor) ignoram a fila para que ainda respondam enquanto ela está parada. | | SN_QUEUE_TIMEOUT_MS | não | SN_TIMEOUT_MS | Tempo máximo que uma solicitação espera por um slot antes de falhar com código BUSY. O tempo de espera não é cobrado no tempo limite por tentativa, apenas em SN_DEADLINE_MS. | | SN_BREAKER_THRESHOLD | não | 0 (desligado) | Disjuntor de circuito opcional por host: após esse número consecutivo de solicitações com falha (erro de transporte, prazo, 5xx), solicitações adicionais falham rapidamente com o código CIRCUIT_OPEN até que SN_BREAKER_RESET_MS passe. Diagnósticos nunca são bloqueados. | | SN_BREAKER_RESET_MS | não | 30000 | Por quanto tempo um disjuntor de circuito aberto rejeita solicitações antes de permitir uma solicitação de teste; a primeira falha o reabre, o primeiro sucesso o fecha. | | SN_INCLUDE_REF_LINKS | não | false | Os campos de referência retornam sem suas URLs link por padrão (economia de tokens). Defina true para incluí-los. | | SN_RESULT_PRETTY | não | false | Os resultados das ferramentas são JSON compacto por padrão (a formatação bonita ~duplica os tokens). Defina true para saída indentada. | | SN_DOCS_DIR | não | docs/instance | Diretório em que o pacote docs lê/escreve Markdown. Caminhos relativos são resolvidos em relação ao diretório de trabalho. Ele também contém o diário de gravação por perfil — adicione docs/instance/ ao .gitignore em qualquer repositório a partir do qual você execute o servidor. | | SN_DOCS_MAX_FILE_BYTES | não | 5242880 | Limite de tamanho por arquivo para as ferramentas de documentação: gravações maiores são recusadas, leituras retornam os primeiros bytes com truncated: true, a pesquisa ignora o arquivo. | | SN_DOCS_STALE_DAYS | não | 30 | servicenow_docs_list sinaliza um documento gerado stale quando seu sn_generated_at é mais antigo que esse número de dias. | | SN_DOCS_SEARCH_MAX | não | 200 | Número máximo de correspondências que servicenow_docs_search retorna; além disso, o resultado carrega truncated: true. | | SN_DIAGRAM_MAX_NODES | não | 200 | Limite de nós para os diagramas Mermaid gerados (fluxo de tabelas, rastreamento de eventos, onde usado; tabelas em um diagrama ER detalhado). Nós além disso são agrupados em um único nó +N more. | | SN_SDK_MANAGED_SCOPES | não | — | P-3: escopos de aplicação separados por vírgula/espaço (namespace como x_acme_app, ou o sys_id sys_scope) que você declara como gerenciados por um projeto ServiceNow SDK (Fluent). A maior fonte de autoridade para detecção gerenciada por SDK; listado em get_status / check_capabilities sob sdkManaged. | | SN_SDK_MANAGED_WRITES | não | warn | P-22: gravações em um escopo gerenciado por SDK (um registro cujo sys_scope P-3 detecta como gerenciado por SDK) de create_record, update_record, upsert_record, delete_record, set_property e revert_write: warn pré-visualiza e aplica com um bloco sdkManaged nomeando a alternativa Fluent; deny recusa a aplicação com SDK_MANAGED_SCOPE (o plano diz would_refuse); allow ignora a verificação. Executa após a política de tabelas e não custa nada, a menos que SN_SDK_MANAGED_SCOPES ou SN_SDK_PROJECT_DIRS esteja definido. | | SN_SDK_PROJECT_DIRS | não | — | P-3: diretórios (separados por vírgulas ou pelo delimitador de caminho da plataforma) verificados somente leitura para projetos SDK: cada now.config.json declara seu scope / scopeId como gerenciado por SDK. Limitado (profundidade 4, 2000 diretórios, 100 arquivos de configuração, 256 KiB por arquivo), nunca segue links simbólicos, ignora pastas ocultas, node_modules e de build, e lê apenas now.config.json. | | SN_CODESEARCH | não | false | Opte pela API de Pesquisa de Código (sn_codesearch) para servicenow_search_code (FT-7). Quando true e o plugin estão ativos, 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 ambiente). |

Política de acesso em dois eixos

O acesso é controlado em dois eixos independentes: tabelas e pacotes de ferramentas.

Desde H-4, as ferramentas apoiadas por plugins (Change, Catalog, Knowledge, Email, ATF) e anexos (através da tabela do registro pai) também obedecem ao eixo de tabelas; o eixo de pacotes ainda remove superfícies inteiras. Consulte Notas de segurança para o modelo completo (incluindo como a API de Lote obedece a ambos os eixos).

Sintaxe de lista: listas de tabelas (SN_TABLES_ALLOW / SN_TABLES_DENY) são separadas por vírgula; 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 — então SN_TABLES_DENY=Change_Request, sys_user funciona. Desde H-11, uma entrada de tabela pode ser um padrão (* qualquer sequência, ? um caractere): SN_TABLES_DENY=sys_* bloqueia sys_user e deixa incident intacto. A ordem é: uma negação exata, uma permissão exata, uma negação por padrão, as tabelas protegidas (gravações, com SN_PROTECTED_TABLES_WRITE=deny), então os padrões da lista de permissões. Pergunte servicenow_explain_policy({table, action}) qual regra decide, ou leia servicenow://policy.

Executar / depurar

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

Observabilidade

• Status. servicenow_get_status carrega um bloco observability: por ferramenta {count, errors, p50, p95, totalMs} (percentis em ms sobre as últimas 256 chamadas de cada ferramenta — a memória permanece limitada), acertos/erros de cache de esquema, contadores de repetição por host, limites e ocupação de fila, estado do disjuntor e os últimos cabeçalhos X-RateLimit-* que cada host enviou. Ele nunca chama a instância.

• Logs. Os logs vão apenas para stderr (stdout é o protocolo MCP). SN_LOG_FORMAT=text alterna de linhas JSON para um formato legível por humanos; SN_LOG_FILE também anexa linhas JSON a um arquivo com rotação de tamanho. Campos nomeados por credenciais (password, token, authorization, …) são mascarados em cada destino, e as regras SN_REDACT_FIELDS / SN_REDACT_PII se aplicam por cima.

• Ganchos de rastreamento. O loop de requisições publica em node:diagnostics_channel, então um assinante OpenTelemetry (ou qualquer um) pode se anexar sem dependência deste servidor:

  Canal	Quando	Campos de mensagem
  servicenow-mcp:http.request.start	uma requisição lógica começa	id, system, method, host, telemetryKey, url, e profile / requestId / sessionId / tool em uma chamada
  servicenow-mcp:http.request.end	resolveu com uma resposta OK	os campos iniciais mais status, attempts, ms
  servicenow-mcp:http.request.error	falhou	os campos iniciais mais attempts, ms, status, code, errorName, errorMessage
  servicenow-mcp:http.request.retry	uma tentativa é repetida (backoff, reautenticação 401)	id, system, method, host, url, attempt, reason, waitMs

  url nunca inclui a string de consulta; cabeçalhos, corpos e credenciais nunca são publicados, e errorMessage passa pelas regras de redação.

• Prometheus. Com o transporte HTTP, SN_METRICS=1 e SN_HTTP_TOKEN definidos, GET /metrics (mesmo token de portador) serve as mesmas figuras no formato de texto Prometheus (famílias servicenow_mcp_*, rotuladas apenas por tool / host). Sem um token, o endpoint permanece desligado e um aviso é registrado.

Interface de linha de comando

O binário publicado servicenow-mcp-ai (execute-o diretamente, ou via npx servicenow-mcp-ai) inicia o servidor MCP quando nenhum comando é fornecido, e caso contrário executa um dos comandos abaixo e sai. As configurações de conexão vêm de variáveis de ambiente / arquivo de ambiente (consulte Variáveis de ambiente). servicenow-mcp-ai --help lista tudo; --version imprime a versão. Um comando ou opção desconhecido imprime o uso em stderr e sai com 2 — ele nunca inicia o servidor.

init escreve através do mesmo gravador de arquivo de ambiente atômico, somente do proprietário (0600) que servicenow_set_credentials, para o arquivo que doctor nomeia (por padrão ~/.config/servicenow-mcp-ai/.env). Ele pergunta, em ordem: a instância (dev12345 ou um host completo; um domínio personalizado precisa de SN_ALLOWED_HOSTS), o método de autenticação (basic / oauth / apikey / token), então as configurações desse método — para oauth a concessão (client_credentials, password, ou authorization_code, que termina com uma dica para executar login). Segredos nunca são ecoados ou registrados; o resumo lista apenas nomes de chaves. Com --profile qa as chaves são escritas como SN_PROFILE_QA_*. Um perfil existente é sobrescrito apenas após um y. As respostas podem ser canalizadas, uma por linha, que é como CI e testes a dirigem:

printf 'dev12345\nbasic\nalice\n%s\n' "$SN_PASSWORD" | npx servicenow-mcp-ai init

Sem um terminal e sem respostas canalizadas, init recusa (saída 2) e não escreve nada.

doctor imprime ASCII simples ([ok] / [x] em vez de marcas de verificação) com --ascii, quando stdout não é um terminal, e no Windows fora do Windows Terminal. --json imprime um documento JSON em vez disso: envFile, status, summary, checks[] (name, ok, detail), config, connection, capabilities e serverStatus (o payload servicenow_get_status) — por exemplo servicenow-mcp-ai doctor --json | jq .checks. Os códigos de saída são os mesmos.

support-bundle coleta o payload doctor --json, cada configuração SN_* com segredos mascarados como ***, npm ls --omit=dev (melhor esforço), o resumo do manifesto de ferramentas (versão, contagens de ferramentas e pacotes, ferramentas ativas) e as últimas 200 linhas de SN_LOG_FILE quando uma está definida. Cada valor mascarado também é limpo de todo o arquivo. O caminho padrão é ./servicenow-mcp-ai-support-<timestamp>.json (modo 0600). Nomes de instância e usuário não são mascarados — revise o arquivo antes de anexá-lo a um problema.

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 de API 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.

Em caso de sucesso, escreve SN_AUTH=oauth, SN_OAUTH_GRANT=refresh_token e SN_OAUTH_REFRESH_TOKEN de volta ao arquivo de ambiente (prefixado por 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 perfil 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 Markdown é escrito em stdout (capture-o como um artefato de CI); um resumo de deriva de uma linha vai para stderr.

Portão de deriva de CI (DF-3)

Compare dois perfis configurados e falhe um pipeline em deriva de configuração:

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

O relatório mostra cada script alterado como um bloco diff. A CLI compara tabelas, colunas, scripts, plugins e aplicativos; seções de registros (sections em servicenow_compare_instances) são opcionais, então os códigos de saída permanecem inalterados.

servicenow_snapshot_instance escreve o mesmo material na pasta de docs, um arquivo por seção, no máximo quatro seções por vez. Uma execução interrompida é marcada partial em index.json; execute novamente com resume: true para pular toda seção cujos arquivos não foram alterados.

Desenvolver

npm run check     # full gate: build, lint, format check, coverage-gated tests, tarball guard, 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 ferramentas em src/tools/, depois execute npm run docs:readme.

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

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

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

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

.
├── .env                   # credentials (git-ignored; or ~/.config/servicenow-mcp-ai/.env)
├── .env.example           # template
├── .github/workflows/     # CI matrix, CodeQL, npm / MCP Registry / Marketplace publishing
├── .vscode/mcp.json       # VS Code MCP server registration
├── bin/                   # CLI launcher (servicenow-mcp-ai.cjs, incl. the doctor command)
├── extension/             # VS Code extension (thin wrapper that registers the server)
├── docs/                  # GitHub Pages site
├── scripts/               # generators + guards (README tools table, tool manifest, coverage guard)
├── src/
│   ├── index.ts           # bootstrap: load env, register, connect transport
│   ├── core/              # HTTP client (auth, retry, SSRF guard), OAuth/JWT/mTLS, policy,
│   │                      # settings, logging, config store, write journal, request
│   │                      # context (profiles); jira/ is a dark scaffold — no tools (ARCH-14)
│   ├── api/               # one module per REST area: table, aggregate, attachment,
│   │                      # importset, batch, catalog, change, knowledge, cmdb, scripts,
│   │                      # flows, codecheck, atf, email, docs, diagrams, meta, doctor,
│   │                      # history, properties, directory, portal…
│   ├── mcp/               # MCP surface: package registry/manifest, tool definition,
│   │                      # resources, prompts, result envelopes, redaction, write mode
│   │                      # (plan/apply), CSV export, stdio + HTTP transports
│   └── tools/             # tool registrations, one file per package (26 packages)
├── test/                  # node:test suite (406 tests): unit, mock-fetch api, MCP smoke, doc guards
└── build/                 # compiled output (after npm run build)