Servicenow Mcp Server

⚙️ ServiceNow MCP サーバー

Bun と TypeScript で構築された、ServiceNow 用の包括的な Model Context Protocol（MCP）サーバーです。28 の ServiceNow ドメインにわたる 176 個のツール、読み取り専用リソース 7 個、ロールベースのツールパッケージ 10 個を提供します。呼び出しごとにインスタンスを指定できる、マルチインスタンス構成に対応しています。

✨ 機能

• ITSM、プラットフォーム開発、サービスカタログ、CMDB、ナレッジ、アジャイルなどにわたる 176 個の MCP ツール
• マルチインスタンス対応 — インスタンスごとの認証で開発／テスト／本番環境を構成し、呼び出しごとに任意のインスタンスを指定できます
• 7 個の MCP リソース — インシデント、ユーザー、ナレッジ、テーブル、スキーマ向けの読み取り専用 servicenow:// URI
• 10 個のツールパッケージ — ロールベースのサブセット（サービスデスク、プラットフォーム開発者、ポータル開発者、インテグレーション開発者など）
• スマートな解決 — ツールでは、人が読める名前（「Beth Anglin」）、レコード番号（「INC0010045」）、または sys_id を指定できます
• 2 種類のトランスポート — stdio（Claude Desktop／Claude Code）と Streamable HTTP（Web インテグレーション）
• Basic 認証と OAuth 2.0 認証に対応し、トークンを自動更新します。設定はインスタンスごとに行います
• 進捗レポート — 実行時間の長い操作（バッチ、クローン、移動）の進捗を MCP クライアントに報告します
• バックグラウンドスクリプトの実行 — sys_trigger 経由でサーバー側の JavaScript を実行します
• プラットフォーム開発を全面的にサポート — ビジネスルール、クライアントスクリプト、UI ポリシー、UI アクション、UI スクリプト、スクリプトインクルード、スクリプト化された REST API、ウィジェット、UI ページ、ワークフロー、Flow Designer
• スクリプトの同期／ローカル開発 — スクリプトをローカルファイルにダウンロードして IDE で編集し、保存時に自動同期します
• アプリケーションスコープ管理 — スコープ付きアプリのコンテキストをプログラムから切り替えます
• 静的なテーブルメタデータ — 高速なスキーマ検索のため、テーブル定義を 100 個事前にキャッシュしています
• @modelcontextprotocol/sdk と zod 以外のランタイム依存関係はありません — Bun がネイティブの fetch、テストランナー、TypeScript を提供します
• 単一の JSON 設定ファイル — 環境変数は不要で、信頼できる情報源を一元化できます

🚀 クイックスタート

前提条件

• Bun v1.0+
• REST API にアクセスできる ServiceNow インスタンス

インストールと設定

git clone [email protected]:seemsindie/servicenow-mcp-server.git
cd servicenow-mcp-server
bun install

# Create your config file
cp config/servicenow-config.example.json config/servicenow-config.json
# Edit with your instance details and credentials

実行（stdio トランスポート）

bun run start
# or with explicit config path:
bun run start -- --config /path/to/config.json

実行（HTTP トランスポート）

bun run start:http
# or:
bun run start:http -- --config /path/to/config.json

# Server starts at http://127.0.0.1:3000
# Health check: GET /health
# MCP endpoint: /mcp

🔧 設定

すべての設定は 1 つの JSON ファイルに記述します。サーバーは次の順序でファイルを検索します。

1. config/servicenow-config.json（cwd からの相対パス）
2. servicenow-config.json（cwd からの相対パス）

または、--config で明示的なパスを指定します。

bun run src/index.ts --config /etc/servicenow/config.json

設定ファイルの形式

{
  "instances": [
    {
      "name": "dev",
      "url": "https://dev-instance.service-now.com",
      "auth": {
        "type": "basic",
        "username": "admin",
        "password": "dev-password"
      },
      "default": true,
      "description": "Development instance"
    },
    {
      "name": "prod",
      "url": "https://prod-instance.service-now.com",
      "auth": {
        "type": "oauth",
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret",
        "username": "admin",
        "password": "prod-password"
      },
      "description": "Production instance"
    }
  ],
  "toolPackage": "full",
  "debug": false,
  "http": {
    "port": 3000,
    "host": "127.0.0.1"
  }
}

設定項目の一覧

認証の種類

Basic 認証：

{ "type": "basic", "username": "admin", "password": "secret" }

OAuth 2.0：

{
  "type": "oauth",
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "username": "admin",
  "password": "secret"
}

各インスタンスで、認証の種類と認証情報を個別に指定します。

🌐 複数インスタンスの使用

すべてのツールで、省略可能な instance パラメーターを使用できます。省略した場合は、デフォルトのインスタンスが使用されます。

# Query incidents on the default instance
sn_query_table(table: "incident", query: "active=true")

# Query incidents on a specific instance
sn_query_table(table: "incident", query: "active=true", instance: "prod")

# List all configured instances
sn_list_instances()

# Get info about a specific instance
sn_instance_info(instance: "dev")

MCP リソース（servicenow:// URI）では、常にデフォルトのインスタンスが使用されます。

🖥️ クライアント連携

すべての連携で同じ MCP サーバーを使用します。/path/to/servicenow-mcp-server を、リポジトリをクローンした実際のパスに置き換えてください。config/servicenow-config.json をプロジェクトディレクトリに配置するか、--config を使用して別の場所を指定してください。

{
  "mcpServers": {
    "servicenow": {
      "command": "bun",
      "args": [
        "run", "/path/to/servicenow-mcp-server/src/index.ts",
        "--config", "/path/to/servicenow-config.json"
      ]
    }
  }
}

claude mcp add servicenow -- bun run /path/to/servicenow-mcp-server/src/index.ts --config /path/to/servicenow-config.json

{
  "mcpServers": {
    "servicenow": {
      "command": "bun",
      "args": [
        "run", "/path/to/servicenow-mcp-server/src/index.ts",
        "--config", "/path/to/servicenow-config.json"
      ]
    }
  }
}

{
  "servers": {
    "servicenow": {
      "command": "bun",
      "args": [
        "run", "/path/to/servicenow-mcp-server/src/index.ts",
        "--config", "/path/to/servicenow-config.json"
      ]
    }
  }
}

{
  "mcp": {
    "servers": {
      "servicenow": {
        "command": "bun",
        "args": [
          "run", "/path/to/servicenow-mcp-server/src/index.ts",
          "--config", "/path/to/servicenow-config.json"
        ]
      }
    }
  }
}

{
  "mcpServers": {
    "servicenow": {
      "command": "bun",
      "args": [
        "run", "/path/to/servicenow-mcp-server/src/index.ts",
        "--config", "/path/to/servicenow-config.json"
      ]
    }
  }
}

{
  "mcpServers": {
    "servicenow": {
      "command": "bun",
      "args": [
        "run", "/path/to/servicenow-mcp-server/src/index.ts",
        "--config", "/path/to/servicenow-config.json"
      ]
    }
  }
}

{
  "mcpServers": {
    "servicenow": {
      "command": "bun",
      "args": [
        "run", "/path/to/servicenow-mcp-server/src/index.ts",
        "--config", "/path/to/servicenow-config.json"
      ]
    }
  }
}

bun run start:http -- --config /path/to/servicenow-config.json
# Server starts at http://127.0.0.1:3000
# MCP endpoint: /mcp
# Health check: GET /health

📦 ツールパッケージ

ロールに応じて公開するツールを制限できます。設定ファイルで toolPackage を指定します。

インスタンス管理ツール（sn_list_instances、sn_instance_info）は、パッケージに関係なく常に利用できます。

🛠️ ツール一覧

インスタンス管理（2 ツール）— 常に利用可能

sn_list_instances、sn_instance_info

汎用テーブル API（5 ツール）

sn_query_table、sn_get_record、sn_create_record、sn_update_record、sn_delete_record

🎫 インシデント（7 ツール）

sn_list_incidents、sn_create_incident、sn_update_incident、sn_add_incident_comment、sn_add_incident_work_notes、sn_resolve_incident、sn_close_incident

スマート解決に対応しています。assigned_to、caller_id、assignment_group には、名前、メールアドレス、sys_id を指定できます。レコード識別子には INC 番号または sys_id を指定できます。

👥 ユーザーとグループ（9 ツール）

sn_list_users, sn_get_user, sn_create_user, sn_update_user, sn_list_groups, sn_create_group, sn_update_group, sn_add_group_members, sn_remove_group_members

グループメンバー関連のツールでは、ユーザー名、メールアドレス、または sys_id と、グループ名または sys_id を指定できます。

🔄 変更管理（10 ツール）

sn_list_change_requests, sn_get_change_request, sn_create_change_request, sn_update_change_request, sn_add_change_task, sn_submit_change_for_approval, sn_approve_change, sn_reject_change, sn_add_change_comment, sn_add_change_work_notes

スマート解決に対応しており、CHG 番号または sys_id を指定できます。また、ユーザーやグループのフィールドは名前で解決されます。

🐛 問題管理（7 ツール）

sn_list_problems, sn_get_problem, sn_create_problem, sn_update_problem, sn_add_problem_comment, sn_add_problem_work_notes, sn_close_problem

📋 サービスリクエスト／RITM（6 ツール）

sn_list_requests, sn_get_request, sn_list_request_items, sn_get_request_item, sn_update_request_item, sn_submit_catalog_request

🛒 サービスカタログ（13 ツール）

sn_list_catalogs, sn_list_catalog_items, sn_get_catalog_item, sn_update_catalog_item, sn_list_catalog_categories, sn_create_catalog_category, sn_update_catalog_category, sn_move_catalog_items, sn_create_catalog_variable, sn_list_catalog_variables, sn_update_catalog_variable, sn_get_catalog_recommendations, sn_validate_catalog_item

sn_validate_catalog_item は、説明の欠落、変数がないこと、アイテムが非アクティブであること、カテゴリの欠落、デフォルト値のない必須変数、重複した変数名、価格の欠落といった一般的な問題をチェックします。

📚 ナレッジベース（8 ツール）

sn_list_knowledge_bases, sn_create_knowledge_base, sn_create_kb_category, sn_list_articles, sn_get_article, sn_create_article, sn_update_article, sn_publish_article

🔀 ワークフロー（9 ツール）

sn_list_workflows, sn_get_workflow, sn_create_workflow, sn_update_workflow, sn_delete_workflow, sn_create_workflow_full, sn_create_workflow_activity, sn_create_workflow_transition, sn_publish_workflow

sn_create_workflow_full は、ワークフローを作成する際に推奨される方法です。基本ワークフロー、バージョン、アクティビティ、遷移（条件は任意）を作成し、必要に応じて公開するまでの全ライフサイクルを、1 回の呼び出しで実行します。遷移の定義では、アクティビティを名前または配列インデックスで参照します。

📝 スクリプトインクルード（5 ツール）

sn_list_script_includes, sn_get_script_include, sn_create_script_include, sn_update_script_include, sn_delete_script_include

▶️ バックグラウンドスクリプトの実行（2 ツール）

sn_execute_background_script, sn_create_fix_script

sn_execute_background_script は、sys_trigger の仕組みを使用して、インスタンス上でサーバーサイドの JavaScript を実行します。約 1 秒後に実行される単発のスケジュール済みトリガーを作成し、GlideRecord／GlideSystem への完全なアクセス権で実行した後、自動的に削除します。

🧩 プラットフォームスクリプトの種類（25 ツール）

5 種類のスクリプトについて、完全な CRUD（一覧表示、取得、作成、更新、削除）を提供します。

🔌 スクリプト化された REST API（7 ツール）

sn_list_scripted_rest_apis、sn_get_scripted_rest_api、sn_create_scripted_rest_api、sn_update_scripted_rest_api、sn_create_rest_resource、sn_update_rest_resource、sn_delete_rest_resource

sn_get_scripted_rest_api は、API 定義とすべてのリソース操作を並行して取得します。sn_create_rest_resource は、HTTP メソッド、パス（{param} 構文に対応）、スクリプトハンドラーを指定してエンドポイントを作成します。

🖼️ Service Portal ウィジェット（5 ツール）

sn_list_widgets、sn_get_widget、sn_create_widget、sn_update_widget、sn_delete_widget

sn_get_widget は、すべてのスクリプトコンポーネント（HTML テンプレート、CSS/SCSS、クライアントスクリプト（Angular コントローラー）、サーバースクリプト、リンク関数、デモデータ、オプションスキーマ）を返します。

📄 UI ページ（5 ツール）

sn_list_ui_pages、sn_get_ui_page、sn_create_ui_page、sn_update_ui_page、sn_delete_ui_page

各 UI ページには、html（Jelly/HTML 本文）、client_script、processing_script（サーバー側）の 3 つのスクリプトコンポーネントがあります。

🌊 Flow Designer（6 ツール）

sn_list_flows、sn_get_flow、sn_create_flow、sn_list_flow_variables、sn_create_flow_variable、sn_list_flow_stages

sn_get_flow は、フロー定義に加えて、すべてのロジックブロックと変数を並行して取得します。

📦 Update Sets（9 ツール）

sn_list_update_sets、sn_get_update_set、sn_create_update_set、sn_update_update_set、sn_set_current_update_set、sn_commit_update_set、sn_add_to_update_set、sn_move_to_update_set、sn_clone_update_set

sn_move_to_update_set は、sys_id、ソースセット、または時間範囲を指定して、進行状況を報告しながらレコードを更新セット間で移動します。sn_clone_update_set は、すべての sys_update_xml レコードを含めてセットを複製します。

🏃 アジャイル（12 ツール）

sn_list_stories、sn_create_story、sn_update_story、sn_list_epics、sn_create_epic、sn_update_epic、sn_list_scrum_tasks、sn_create_scrum_task、sn_update_scrum_task、sn_list_projects、sn_create_project、sn_update_project

🖧 CMDB（5 ツール）

sn_list_ci、sn_get_ci、sn_create_ci、sn_list_ci_relationships、sn_create_ci_relationship

🔍 スキーマ検出（4 ツール）

sn_get_table_schema、sn_discover_table、sn_list_tables、sn_explain_field

sn_explain_field は、型、参照先、最大長、選択肢、デフォルト値など、特定のフィールドに関する詳細なメタデータを提供します。スキーマツールは、事前に読み込まれた 100 個のテーブル定義を静的キャッシュに保存しており、すばやく検索できます。

🔎 自然言語検索（1 ツール）

sn_natural_language_search — 平易な英語を ServiceNow のエンコード済みクエリに変換します（16 種類のパターンマッチャー）。

🎯 アプリケーションスコープ（2 ツール）

sn_get_current_application、sn_set_application_scope

スコープ付きアプリでレコードを作成する前に、アクティブなアプリケーションスコープを切り替えます。sys_id またはスコープ文字列（例：x_myapp_module）を受け付けます。

💻 スクリプト同期／ローカル開発（3 ツール）

sn_sync_script_to_local、sn_sync_local_to_script、sn_watch_and_sync

ローカル開発のワークフロー：

1. sn_sync_script_to_local — 任意のスクリプトレコードをローカルファイルにダウンロードします。複数フィールドを持つレコード（ウィジェット、UI ページ）では、サブディレクトリにコンポーネントごとのファイルが作成されます。.sn-sync.json マニフェストを作成します。
2. IDE で構文ハイライト、リンティング、IntelliSense を利用して編集します。
3. sn_sync_local_to_script — ローカルファイルを ServiceNow にプッシュします。マニフェストから同期先を自動検出します。
4. sn_watch_and_sync — ファイルの変更を監視し、保存時に自動同期します（2 秒間隔でポーリング）。バックグラウンドで実行されます。

⚡ 一括操作（3 ツール）

sn_batch_create、sn_batch_update、sn_batch_delete — 進行状況を報告しながら、複数のテーブルにわたってレコードを並行して作成、更新、削除します。

📎 添付ファイル（3 ツール）

sn_upload_attachment、sn_list_attachments、sn_get_attachment

任意のレコードにファイルをアップロードし、レコードの添付ファイルを一覧表示し、添付ファイルのメタデータやコンテンツを取得します。

📊 集計（1 ツール）

sn_aggregate_table — グループ化とエンコードされたクエリフィルターを任意で指定し、/api/now/stats エンドポイントを使用して集計クエリ（COUNT、SUM、AVG、MIN、MAX）を実行します

📥 インポートセット（2 ツール）

sn_create_import_set、sn_run_transform

インポートセットの行を作成し、変換マップを実行して、プログラムからServiceNowのテーブルにデータを読み込みます。

📡 MCP リソース

リソースは常にデフォルトインスタンスを使用します。

🧪 開発

# Type check
bun run typecheck

# Run tests (279 tests across 26 files)
bun test

# Dev mode (auto-reload)
bun run dev

🏗️ アーキテクチャ

src/
  index.ts          # stdio entry point (--config support)
  http.ts           # Streamable HTTP entry point (--config support)
  server.ts         # MCP server setup, modular tool registration
  config.ts         # JSON config loader + Zod validation
  auth/             # Basic & OAuth providers (per-instance)
  client/
    index.ts        # ServiceNow REST client
    registry.ts     # InstanceRegistry — maps instance names to clients
    errors.ts       # SN-specific error classes
    types.ts        # API response types
  config/
    table-definitions.json  # 100 pre-cached table definitions
  tools/            # 28 domain tool modules
    tables.ts               # Generic Table API CRUD (any table)
    incidents.ts            # Incident management + smart resolution
    changes.ts              # Change requests + tasks + approvals
    users.ts                # Users, groups, members
    catalog.ts              # Service catalog items/categories/variables/validation
    knowledge.ts            # Knowledge bases, categories, articles
    workflows.ts            # Workflows + orchestration (version/activities/transitions/publish)
    scripts.ts              # Script includes
    changesets.ts           # Update sets + move/clone
    agile.ts                # Stories, epics, scrum tasks, projects
    cmdb.ts                 # CMDB CIs + relationships
    schema.ts               # Schema discovery / table introspection
    search.ts               # Natural language search
    batch.ts                # Batch create/update/delete with progress
    background-scripts.ts   # Background script execution via sys_trigger
    platform-scripts.ts     # Business rules, client scripts, UI policies/actions/scripts
    scripted-rest.ts        # Scripted REST API definitions + operations
    widgets.ts              # Service Portal widgets (sp_widget)
    ui-pages.ts             # UI pages (sys_ui_page)
    flows.ts                # Flow Designer (sys_hub_flow + related)
    app-scope.ts            # Application scope management
    script-sync.ts          # Script sync / local development workflow
    problems.ts             # Problem management
    requests.ts             # Service requests + requested items (RITM)
    attachments.ts          # File attachments (upload/list/get)
    aggregation.ts          # Aggregate stats (COUNT/SUM/AVG/MIN/MAX)
    import-sets.ts          # Import sets + transform maps
    instances.ts            # Instance management (always available)
  resources/        # 7 servicenow:// MCP resources (default instance)
  packages/         # 10 role-based tool package definitions
  utils/
    logger.ts               # Logger (stderr-safe)
    query.ts                # Encoded query builder
    resolve.ts              # Smart name/number resolution
    progress.ts             # MCP progress notification helper
    table-metadata.ts       # Static table metadata loader

config/
  servicenow-config.example.json  # Config template

📦 依存関係

• @modelcontextprotocol/sdk — MCP プロトコルの実装
• zod — スキーマ検証

実行時の依存関係はほかにありません。Bunはネイティブのfetch、テストランナー、TypeScriptの実行機能を提供します。

📄 ライセンス

MIT