Servicenow Mcp Server

⚙️ ServiceNow MCP 服务

这是一个适用于 ServiceNow 的综合 Model Context Protocol（MCP）服务，基于 Bun 和 TypeScript 构建。提供涵盖 28 个 ServiceNow 领域的 176 个工具、7 个只读资源，以及 10 个基于角色的工具包。支持多实例配置，可针对每次调用指定实例。

✨ 功能

• 176 个 MCP 工具，涵盖 ITSM、平台开发、服务目录、CMDB、知识、敏捷等领域
• 多实例支持 — 配置开发、测试和生产环境，并为每个实例单独设置身份验证；可针对每次调用指定任意实例
• 7 个 MCP 资源 — 用于事件、用户、知识、表和架构的只读 servicenow:// URI
• 10 个工具包 — 基于角色的工具子集（服务台、平台开发人员、门户开发人员、集成开发人员等）
• 智能解析 — 工具接受易读名称（“Beth Anglin”）、记录编号（“INC0010045”）或 sys_id
• 两种传输方式 — 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

🔧 配置

所有配置都保存在一个 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 是创建工作流的推荐方式——通过一次调用编排完整生命周期：创建基础工作流、版本、活动、转换（可选条件），并可选择发布。在转换定义中，可通过名称或数组索引引用活动。

📝 脚本包含项（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 个工具）

为五种脚本类型提供完整的 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（服务端脚本）。

🌊 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 会并行获取流程定义及所有逻辑块和变量。

📦 更新集（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