ServiceNow连接器

ServiceNow MCP Server

O ServiceNow MCP Server é um conector de alta performance que permite que agentes de IA (Claude, GitHub Copilot, Antigravity) desenvolvam e gerenciem instâncias do ServiceNow diretamente via APIs nativas.

v7.2.0 — 47 ferramentas ativas, 4 MCP Prompts. Consolidação de System Properties (3→1: sn_manage_sys_property) e Attachments (3→1: sn_manage_attachment). Fluxo de governança sn_generate_execution_plan + prompt safe_change_request. Dashboard v3.0 com Graph Explorer (D3.js), Schema Search e Latency Heatmap.

Índice

• Requisitos
• Instalação Rápida
• Configuração do Ambiente (.env)
• Instalação por Plataforma
  • Claude Desktop
  • Claude Code (CLI)
  • VS Code + GitHub Copilot
  • Antigravity (Google Agentspace)
• Dashboard v3.0
• Incremental Harvester
• Build & Testes
• Ferramentas Disponíveis
• MCP Prompts
• Changelog

Requisitos

• Node.js >= 18 (Recomendado: >= 20)
• npm >= 9
• Credenciais ServiceNow (Basic Auth ou OAuth 2.0)

Instalação Rápida

git clone https://github.com/jeffersonrmoraes/servicenow-mcp.git
cd servicenow-mcp
npm install

Configuração do Ambiente (.env)

O servidor carrega automaticamente as variáveis do arquivo .env na raiz.

# Exemplo 1: Ambiente PDI
PDI_SN_INSTANCE=dev12345
PDI_SN_USER=admin
PDI_SN_PASSWORD=sua_senha

# Exemplo 2: Ambiente DEV
DEV_SN_INSTANCE=dev99999
DEV_SN_USER=admin
DEV_SN_PASSWORD=outra_senha

# Instância padrão (sem prefixo)
SN_INSTANCE=dev88888
SN_USER=admin
SN_PASSWORD=senha_padrao

# Cache persistente (opcional)
SN_CACHE_PERSIST=true
SN_CACHE_PERSIST_PATH=.sn-cache.json

# Activity log (opcional — sobrepõe o caminho padrão)
SN_ACTIVITY_LOG_PATH=.sn-activity.jsonl

Use o parâmetro env nas ferramentas para rotear entre ambientes:

• env: "PDI" → usa PDI_SN_INSTANCE, PDI_SN_USER, etc.
• env: "DEV" → usa DEV_SN_INSTANCE, DEV_SN_USER, etc.
• env: "" (ou omitido) → usa as variáveis sem prefixo (SN_INSTANCE, etc.)

Instalação por Plataforma

Claude Desktop

Abra seu claude_desktop_config.json e adicione a configuração exata baseada no seu diretório:

{
  "mcpServers": {
    "servicenow-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "c:/servicenow-mcp/servicenow-mcp/src/index.ts"
      ],
      "workingDirectory": "c:/servicenow-mcp/servicenow-mcp",
      "disabled": false
    }
  }
}

Claude Code (CLI)

claude mcp add servicenow -- npx tsx /caminho/para/servicenow-mcp/src/index.ts

Ou configure via .mcp.json na raiz do projeto:

{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["tsx", "/caminho/para/servicenow-mcp/src/index.ts"]
    }
  }
}

VS Code + GitHub Copilot

Em .vscode/mcp.json:

{
  "servers": {
    "servicenow": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/caminho/para/servicenow-mcp/src/index.ts"]
    }
  }
}

Antigravity (Google Agentspace)

Configure o servidor como stdio apontando para o arquivo principal. Configuração recomendada:

• Command: npx
• Args: ["-y", "tsx", "c:/servicenow-mcp/servicenow-mcp/src/index.ts"]
• Working Directory: c:/servicenow-mcp/servicenow-mcp

Dashboard v3.0

O Dashboard é um painel web local que roda em paralelo ao servidor MCP, sem interferir na latência das ferramentas.

npm run dashboard
# Acesse: http://localhost:3000

Funcionalidades

Linter de Update Sets (15 checks)

Incremental Harvester

O Harvester sincroniza metadados da instância localmente em knowledge/. Usa sys_updated_on para baixar apenas o que mudou desde o último sincronismo (knowledge/state.json). Default: 50 tabelas por execução.

# Sincroniza apenas as mudanças desde a última execução
npm start -- sn_sync_knowledge_base --category CORE

# Força sincronismo completo
npm start -- sn_sync_knowledge_base --force

# Com garbage collection (remove schemas obsoletos)
npm start -- sn_sync_knowledge_base --force --cleanup

Os schemas ficam em knowledge/core/, knowledge/custom/ e knowledge/system/.

Build & Testes

# Type-check sem build
npm run type-check

# Build para produção (gera dist/)
npm run build

# Testes (TypeScript direto)
npm test

# Modo desenvolvimento com hot-reload
npm run dev

# Dashboard (http://localhost:3000)
npm run dashboard

# Tool Scaffolder — gera boilerplate de novo módulo
npm run add-tool <module> <sn_tool_name>
# Exemplo: npm run add-tool reporting sn_export_dashboard

Ferramentas Disponíveis

47 ferramentas organizadas em 17 módulos.

Core CRUD

Metadados & Código

IA & Contexto

Front-end & UX

Service Catalog

Flow Designer

Segurança & Acesso

Deploy & Update Sets

Logs & Observabilidade

Attachments

System Properties

Utilitários

MCP Prompts

O servidor expõe 4 prompts predefinidos que guiam agentes de IA em workflows comuns:

Governança de Mudanças — Fluxo Plan → Impact → Approval

A partir da v7.1.0, o MCP oferece um fluxo de segurança consultivo para operações mutantes. O prompt safe_change_request instrui o agente a:

1. Planejar — chamar sn_generate_execution_plan para gerar um plano detalhado
2. Analisar o impacto — a ferramenta consulta a instância em tempo real (Business Rules, Client Scripts, ACLs, registros afetados)
3. Pedir aprovação — se requires_approval: true, o agente para e aguarda confirmação explícita do usuário antes de executar qualquer operação

Importante: O fluxo é consultivo — o MCP não bloqueia tecnicamente chamadas subsequentes. O prompt guia a IA a interromper e solicitar aprovação explícita do usuário.

sn_generate_execution_plan — Parâmetros

O retorno inclui report_markdown com plano completo, requires_approval (boolean), e campo steps estruturado com ferramenta e nível de risco por passo.

Segurança

• Operações de delete: Completamente removidas por política de segurança. Use a interface do ServiceNow para operações destrutivas.
• Script sanitization: sn_execute_script e sn_upsert_metadata_script bloqueiam operações perigosas (deleteMultiple, Packages.java, Runtime, etc.).
• OAuth tokens: Armazenados apenas em memória durante a sessão. Nunca persistidos em .env via código.
• Retry: Backoff exponencial automático para erros 429, 500, 502, 503, 504.
• LRU Cache: Limite máximo de entradas para prevenir memory leaks. Persistência opcional em JSON.
• Admin guard: sn_stream_syslog e sn_get_node_log verificam a role admin via API antes de executar.

Changelog

Para Agentes de IA

Leia as convenções em GEMINI.md e o guia de uso em AI_REFERENCE.md antes de qualquer intervenção.