ServiceNow MCP Reports

Local MCP server exposing two on-demand ServiceNow reports, built from the plan in [[ServiceNow MCP Server — Syslog & Dev Work Reports (Plan)]]. Setup narrative and troubleshooting also live in the vault: [[ServiceNow MCP Server — Syslog & Dev Work Reports (Setup Guide)]].

For ideas on extending this beyond the two current tools, see echelon-ai-labs/servicenow-mcp — a much larger Python/FastMCP ServiceNow server (incidents, changes, catalog, knowledge base, script includes, Agile tools). Already borrowed from it: a remote-reachable HTTP transport alongside stdio (step 7) — that repo exposes both stdio and SSE; and its date-range filters use ServiceNow's own relative-date keywords (ONLast week@javascript:gs.beginningOfLastWeek()@javascript:gs.endOfLastWeek()) rather than constructing literal datetimes by hand — comparing that pattern against this project's own query is what surfaced the timezone bug fixed in step 4/Troubleshooting below. Not yet borrowed: its AuthManager, which supports Basic/OAuth/API-key behind one interface (this project is Basic-only).

Tools

Both are read-only GET queries against the Table API — neither tool ever writes to the instance. Both return raw/grouped rows only; analysis (suggested fixes, flagged concerns) happens in conversation with Claude, not inside the tool. Both paginate automatically (queryTableAll in servicenow-client.ts, 1000 rows/page, 10,000-row safety cap) instead of a hardcoded single-page sysparm_limit — if a query hits the cap, the response leads with an explicit ⚠ Truncated text block before the JSON, rather than silently returning a partial report. Registered for both entrypoints from the same src/create-server.ts.

get_syslog_report

Fetch syslog rows for a single day, filtered to warning/error by default.

Возвращает JSON-массив:

{
  "sys_created_on": "2026-08-25 17:30:24",
  "message": "SG-Azure Request failed with statusCode: 403 Code: AccessDenied ...",
  "source": "sn_sg_azure_integ",
  "level": "2",
  "node": "..."
}

get_developer_work_report

Fetch sys_update_xml changes between two dates, grouped by author and update set.

Возвращает JSON-массив:

{
  "author": "system",
  "updateSet": "Default",
  "isDefaultUpdateSet": true,
  "changeCount": 2,
  "changes": [
    { "name": "...", "type": "Service Graph Connections State", "created": "2026-08-25 10:30:30" }
  ]
}

Related MCP server: ServiceNow MCP Server

1. Создание учётной записи ServiceNow с доступом только на чтение (вручную, однократно)

Do this in the PDI (https://dev203275.service-now.com), logged in as an admin:

1. User Administration → Users → New

   • User ID: claude_mcp_readonly

   • Set a password, uncheck "Password needs reset"

   • Check "Web service access only" — обязательно. Без этого SNCRestrictBasicAuthUserAuthenticationGate ServiceNow блокирует Basic Auth по REST для этой учётной записи даже при правильном пароле, поскольку учётная запись также допускает интерактивный вход в UI. Симптом при пропуске: каждый REST-вызов возвращает 401 с "User is not authenticated", при этом вход в UI с теми же учётными данными работает. См. раздел «Устранение неполадок».

2. В записи этого пользователя → связанный список Roles → Edit → добавьте:

   • rest_api_explorer (доступ к REST API)

   • Доступ на чтение к syslog и sys_update_xml/sys_update_set — на PDI роли snc_read_only или встроенной itil обычно достаточно; убедитесь, что пользователь действительно может читать эти таблицы (см. шаг 3 ниже), а не просто полагайтесь на название роли.

   • Не предоставляйте роль admin — эта учётная запись должна только выполнять запросы, согласно исходному плану.

3. Скопируйте .env.example в .env и заполните SN_USER / SN_PASS данными новой учётной записи.

2. Сборка

cd C:\Users\willr\projects\servicenow-mcp-reports
npm install
npm run build

3. Проверка учётных данных перед подключением к клиенту

$env:SN_INSTANCE="https://dev203275.service-now.com"; $env:SN_USER="claude_mcp_readonly"; $env:SN_PASS="<password>"
node -e "fetch(process.env.SN_INSTANCE+'/api/now/table/sys_user?sysparm_limit=1',{headers:{Authorization:'Basic '+Buffer.from(process.env.SN_USER+':'+process.env.SN_PASS).toString('base64')}}).then(r=>console.log(r.status))"

Должно вывестись 200. При 401 проверьте пароль; при 403 роль пока не покрывает доступ к этой таблице.

4. Имя таблицы syslog, значения уровней и фильтрация по дате (решено)

Подтверждено для этого экземпляра 2026-08-26:

• Таблица называется syslog, а не sys_log (sys_log возвращает 400 Invalid table sys_log).

• syslog.level является числовым, а не строками "warning"/"error": -2=Trace, -1=Debug, 0=Information, 1=Warning, 2=Error, 3=Fatal (подтверждено через GET /api/now/table/sys_choice?sysparm_query=name=syslog^element=level).

• Фильтр диапазона дат должен использовать простые литеральные значения даты и времени ('<date> 00:00:00'@'<date> 23:59:59'), а не javascript:gs.dateGenerate(...) — см. «Устранение неполадок», почему последний вариант молча смещал результаты на другой день.

src/tools/syslog.ts внутренне сопоставляет дружественные имена уровней ("warning", "error" и т. д.) с этими кодами, поэтому вызывающие стороны могут продолжать передавать имена — это важно только при расширении инструмента или подключении к другому экземпляру, где сопоставление следует перепроверить тем же запросом sys_choice.

5. Регистрация в Claude Code CLI

claude mcp add --scope user servicenow-reports -- "C:\Program Files\nodejs\node.exe" C:\Users\willr\projects\servicenow-mcp-reports\dist\index.js

Используйте абсолютный путь к node.exe, а не просто node — сеанс Claude Code, запущенный до того, как Node оказался в PATH, не сможет разрешить команду node при запуске сервера (claude mcp list покажет CONNECTION_CLOSED). Проверьте с помощью claude mcp list.

CLI Claude Code читает SN_INSTANCE/SN_USER/SN_PASS из .env в папке этого проекта — дополнительная настройка переменных окружения на стороне CLI не требуется, пока .env существует здесь. Это работает благодаря тому, что src/index.ts определяет путь к .env относительно самого скомпилированного скрипта (import.meta.url), а не process.cwd() — обычный import "dotenv/config" не сработал бы, поскольку Claude Code запускает этот сервер из постороннего рабочего каталога. См. «Устранение неполадок», если .env перестанет загружаться.

6. Регистрация в Claude Desktop

Добавьте в %APPDATA%\Claude\claude_desktop_config.json (создан с нуля — на этой машине его не было):

{
  "mcpServers": {
    "servicenow-reports": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\willr\\projects\\servicenow-mcp-reports\\dist\\index.js"],
      "env": {
        "SN_INSTANCE": "https://dev203275.service-now.com",
        "SN_USER": "claude_mcp_readonly",
        "SN_PASS": "<password>"
      }
    }
  }
}

Claude Desktop запускает сервер как отдельный процесс, не наследуя .env этого проекта, поэтому учётные данные здесь указаны явно. После редактирования перезапустите Claude Desktop и проверьте значок разъёма 🔌, чтобы убедиться, что подключение установлено.

7. Опционально: HTTP-транспорт с удалённым доступом

На шагах 5–6 используется stdio, который работает только для клиента, способного запускать локальный процесс (Claude Code, Claude Desktop). Клиенту, который не может этого делать — например, размещённым в claude.ai запланированным задачам (Scheduled Tasks) — вместо этого нужна HTTP-конечная точка. src/http.ts предоставляет те же два инструмента через Streamable HTTP-транспорт MCP по адресу POST/GET /mcp.

npm run build
$env:MCP_HTTP_TOKEN="<pick something random>"; npm run start:http

По умолчанию сервер привязывается к 127.0.0.1:3535 (переопределяется через MCP_HTTP_HOST / MCP_HTTP_PORT в .env). Если задан MCP_HTTP_TOKEN, каждый запрос должен отправлять Authorization: Bearer <token>, иначе возвращается 401; если токен не задан, сервер выводит предупреждение в лог и принимает неаутентифицированные запросы — это допустимо, только пока сервер привязан к localhost, и недопустимо, если он когда-либо окажется за публичным туннелем. createMcpExpressApp() (из SDK) также автоматически включает защиту от DNS-rebinding при привязке к хосту localhost.

Чтобы действительно получить доступ к этому серверу из размещённых в claude.ai запланированных задач, 127.0.0.1 недостаточно — нужен публичный URL (например, туннель: ngrok http 3535, или реальное развёртывание). Это отдельный шаг, здесь он не выполняется; сейчас добавляется только сама возможность. Сначала выполните быстрый локальный тест:

curl.exe -s -X POST http://127.0.0.1:3535/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer $env:MCP_HTTP_TOKEN" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoketest","version":"0.0.1"}}}'

Должен вернуться ответ 200 с заголовком mcp-session-id и телом JSON-RPC result.

Устранение неполадок

• 401 на каждом REST-вызове, несмотря на правильный пароль, но вход в UI ServiceNow с теми же учётными данными работает — это SNCRestrictBasicAuthUserAuthenticationGate: он блокирует Basic Auth по REST для учётных записей, которые также могут входить интерактивно. Исправление: установите флажок "Web service access only" в записи пользователя (шаг 1). Не тратьте время на повторный сброс пароля — такая картина (вход в UI успешен, REST возвращает 401, "User is not authenticated" / "Required to provide Auth information") указывает на этот шлюз, а не на неверные учётные данные. Это можно диагностировать прямо из системных журналов (/syslog_list.do, фильтр по имени учётной записи).

• Invalid table sys_log (HTTP 400) — таблица называется syslog, без подчёркивания.

• Отчёт возвращается пустым, хотя логи за этот день существуют — level в этом экземпляре числовой (см. шаг 4), а не строки "warning"/"error". Перепроверьте сопоставление с помощью запроса sys_choice, если подключаетесь к другому экземпляру.

• Missing SN_INSTANCE, SN_USER, or SN_PASS environment variables" при запуске в качестве реального MCP-сервера, даже если .env существует и прямой запуск node dist/index.js из этой папки работает нормально — прямой запуск успешен потому, что его process.cwd() оказывается папкой проекта; Claude Code запускает сервер из другого места, поэтому обычный dotenv/config молча не срабатывает. Убедитесь, что src/index.ts определяет путь к .env через import.meta.url, а не через cwd (см. шаг 5). Всегда проверяйте реальным вызовом инструмента MCP, а не только прямым запуском скрипта — эти два способа могут давать разные результаты.

• get_syslog_report молча возвращает не тот день / отсутствует несколько часов — это была реальная ошибка, обнаруженная 2026-08-26 при выборочной проверке в сравнении с паттернами запросов echelon-ai-labs/servicenow-mcp. src/tools/syslog.ts раньше строил фильтр дат с помощью sys_created_onBETWEENjavascript:gs.dateGenerate('<date>','00:00:00')@javascript:gs.dateGenerate(...). gs.dateGenerate() вычисляет значение в часовом поясе, настроенном в экземпляре, но sys_created_on через Table API возвращается как сырое значение UTC — поэтому окно молча смещалось на дельту UTC экземпляра (~7 часов на этом PDI), захватывая хвост не того дня и теряя ранние часы нужного. Исправлено полным удалением обёртки javascript:gs.dateGenerate(...) и передачей простых литеральных строк '<date> 00:00:00'@'<date> 23:59:59', которые сравниваются напрямую с сырым сохранённым значением без преобразования часового пояса. Проверено: 834 строки за все 24 часа 2026-08-25 против 366 строк за 17 часов до исправления. Если настройка часового пояса экземпляра когда-либо изменится, перепроверьте тем же тестом покрытия всех часов (см. выборочную проверку в стиле шага 4), а не полагайтесь на предположения.

• CONNECTION_CLOSED в claude mcp list — сеанс CLI был запущен до того, как Node.js оказался в PATH. Зарегистрируйте сервер с абсолютным путём к node.exe (уже сделано на шаге 5) или начните новый сеанс.

• Изменил код, пересобрал, но поведение не изменилось — уже запущенный сеанс Claude Code продолжает использовать старый dist/, загруженный через stdio-соединение. Выполните команду /mcp в этом сеансе, чтобы переподключиться; перезапуск не требуется.

Файлы

• src/servicenow-client.ts — обёртка над Table API (Basic Auth) плюс queryTableAll, цикл пагинации, который используют оба инструмента (1000 строк/страница, безопасный предел в 10 000 строк, возвращает { rows, truncated }). Позже здесь можно заменить Basic Auth на OAuth, если вы перейдёте с PDI.

• src/tools/syslog.ts, src/tools/dev-work-report.ts — два запроса отчётов.

• src/create-server.ts — создаёт McpServer и регистрирует оба инструмента; используется обеими точками входа ниже.

• src/index.ts — точка входа stdio (Claude Code/Desktop); определяет путь к .env относительно самого себя (а не cwd).

• src/http.ts — точка входа Streamable HTTP (шаг 7); аутентификация по bearer-токену, один сервер+транспорт на сеанс.