ServiceNow MCP Reports

オンデマンドの ServiceNow レポートを2つ公開するローカル MCP サーバー。[[ServiceNow MCP Server — Syslog & Dev Work Reports (Plan)]] の計画に基づいて構築されています。セットアップの解説とトラブルシューティングもボールトにあります: [[ServiceNow MCP Server — Syslog & Dev Work Reports (Setup Guide)]]。

この2つのツールを超えて拡張するアイデアについては、echelon-ai-labs/servicenow-mcp を参照してください。はるかに大規模な Python/FastMCP ServiceNow サーバーです（インシデント、変更、カタログ、ナレッジベース、スクリプトインクルード、Agile ツール）。そこから既に借用したもの: stdio に加えてリモートから到達可能な HTTP トランスポート（ステップ7）— そのリポジトリは stdio と SSE の両方を公開しています。また、日付範囲フィルタは、日時リテラルを手作業で構築する代わりに、ServiceNow 独自の相対日付キーワード（ONLast week@javascript:gs.beginningOfLastWeek()@javascript:gs.endOfLastWeek()）を使用しています。そのパターンをこのプロジェクトの独自クエリと比較したことで、下記のステップ4／トラブルシューティングで修正したタイムゾーンのバグが明らかになりました。まだ借用していないもの: その AuthManager は、1つのインターフェースの背後で Basic/OAuth/API-key をサポートしています（このプロジェクトは Basic のみ）。

Tools

両方とも Table API に対する読み取り専用の GET クエリであり、いずれのツールもインスタンスに書き込むことはありません。どちらも生の行／グループ化された行のみを返します。分析（推定される修正、フラグ付きの懸念事項）はツール内ではなく、Claude との会話の中で行われます。両方とも自動ページネーションを行います（servicenow-client.ts 内の queryTableAll、1000 行/ページ、10,000 行の安全上限）。ハードコードされた単一ページの sysparm_limit は使いません。クエリが上限に達した場合は、JSON の前に明示的な ⚠ Truncated テキストブロックを先頭に付けて応答し、部分レポートを黙って返すことはありません。両エントリポイントに対して同じ src/create-server.ts から登録されます。

get_syslog_report

syslog の行を1日分取得します。デフォルトでは警告/エラーにフィルタリングされます。

次の 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

2つの日付の間の sys_update_xml の変更を、作成者と更新セットごとにグループ化して取得します。

次の 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 サービスアカウントを準備する（手動、1回限り）

PDI（https://dev203275.service-now.com）で管理者としてログインして行います:

1. ユーザー管理 → ユーザー → 新規

   • ユーザー ID: claude_mcp_readonly

   • パスワードを設定し、「パスワードのリセットが必要」 のチェックを外します。

   • 「Web サービスのみアクセス」 にチェックを入れます — 必須。これがないと、ServiceNow の SNCRestrictBasicAuthUserAuthenticationGate は、正しいパスワードでもこのアカウントに対する REST 経由の Basic Auth をブロックします。このアカウントは対話型 UI ログインも許可されているためです。見逃した場合の症状: 同じ資格情報で UI にログインできるのに、すべての REST 呼び出しが "User is not authenticated" で 401 になります。トラブルシューティングを参照。

2. そのユーザーレコードで → ロール 関連リスト → 編集 → 追加:

   • 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. Build

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 ではありません。Node が PATH に追加される前に開始された Claude Code セッションは、サーバーを起動するときに素の node コマンドを解決できません（claude mcp list に CONNECTION_CLOSED と表示されます）。claude mcp list で確認してください。

Claude Code CLI は、このプロジェクトフォルダー内の .env から SN_INSTANCE/SN_USER/SN_PASS を読み取ります。ここに .env が存在する限り、CLI 側で追加の環境設定は不要です。これは 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 は、MCP の Streamable HTTP トランスポートを介して、POST/GET /mcp で同じ2つのツールを公開します。

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

デフォルトでは 127.0.0.1:3535 にバインドします（.env の MCP_HTTP_HOST / MCP_HTTP_PORT で上書き可能）。MCP_HTTP_TOKEN が設定されている場合、すべてのリクエストは Authorization: Bearer <token> を送信する必要があり、そうしないと 401 になります。設定されていない場合、サーバーは警告をログに記録し、認証なしのリクエストを受け入れます。localhost にのみバインドしている間は問題ありませんが、公開トンネルの背後に置かれる場合は問題です。createMcpExpressApp()（SDK から）は、localhost ホストにバインドされるときは常に DNS リバインディング保護も自動的に有効にします。

claude.ai のホスト型 Scheduled Tasks から実際に到達するには、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 ボディが返されるはずです。

トラブルシューティング

• 正しいパスワードにもかかわらずすべての REST 呼び出しで 401 が返るが、同じ資格情報で ServiceNow UI にはログインできる — これは SNCRestrictBasicAuthUserAuthenticationGate です。対話型ログインもできるアカウントに対して、REST 経由の Basic Auth をブロックします。修正: ユーザーレコードで 「Web サービスのみアクセス」 にチェックを入れます（ステップ1）。パスワードの再設定に時間を費やさないでください。そのパターン（UI ログインは OK、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 クエリでマッピングを再確認してください。

• 実際の MCP サーバーとして起動したときに Missing SN_INSTANCE, SN_USER, or SN_PASS environment variables" というエラーが発生する。.env は存在し、このフォルダーから直接 node dist/index.js を実行するテストは正常に動作するにもかかわらず — その直接テストが成功するのは、その process.cwd() がたまたまプロジェクトフォルダーであるためです。Claude Code は別の場所からサーバーを起動するため、素の dotenv/config は静かに失敗します。src/index.ts が .env を cwd ではなく import.meta.url 経由で解決していることを確認してください（ステップ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 差分（この PDI では約7時間）だけ静かにずれ、誤った日付の末尾を取り込み、正しい日付の早朝の時間が欠落していました。javascript:gs.dateGenerate(...) ラッパーを完全に削除し、プレーンなリテラル '<date> 00:00:00'@'<date> 23:59:59' 文字列を渡すことで修正しました。これはタイムゾーン変換なしで生の保存値と直接比較されます。検証済み: 修正前は17時間で366行でしたが、修正後は2026-08-25の全24時間で834行でした。このインスタンスのタイムゾーン設定が変更された場合は、推測せずに同じ全時間カバレッジチェック（ステップ4形式のスポットチェック）で再検証してください。

• claude mcp list で CONNECTION_CLOSED が表示される — CLI セッションが Node.js が PATH に追加される前に開始されました。node.exe の絶対パスで登録するか（ステップ5で済み）、新しいセッションを開始してください。

• コードを編集して再ビルドしたのに動作が変わらない — 実行中の Claude Code セッションは、stdio 接続を介して古い dist/ を読み込んだままです。そのセッションで /mcp を実行して再接続してください。再起動は不要です。

ファイル

• src/servicenow-client.ts — Table API ラッパー（Basic Auth）と queryTableAll。両ツールが使用するページネーションループです（1000行/ページ、10,000行の安全上限、{ rows, truncated } を返します）。PDI から移行する場合は、ここで後で Basic Auth を OAuth に交換してください。

• src/tools/syslog.ts, src/tools/dev-work-report.ts — 2つのレポートクエリ。

• src/create-server.ts — McpServer を構築し、両方のツールを登録します。下記の両エントリポイントで共有されます。

• src/index.ts — stdio エントリポイント（Claude Code/Desktop）。.env を自身からの相対パス（cwd ではなく）で解決します。

• src/http.ts — Streamable HTTP エントリポイント（ステップ7）。ベアラートークン認証、セッションごとに1つのサーバー＋トランスポート。