Skip to main content
Glama
Sign In
servicenow-platform-mcp

servicenow-platform-mcp

by Xerrion
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

ServiceNow Platform MCP

Connect your AI app to ServiceNow to read tickets, inspect configuration, and prepare changes to records or scripts. The server uses the Model Context Protocol (MCP).

Sign in with your ServiceNow account. Your roles, API access policies, and access control rules (ACLs) determine what you can read or change.

Start here

If the server is already configured, ask your AI app:

Use ServiceNow to show 5 active incidents I can access. Include the incident number, short description, priority, and assigned person. Do not change anything.

If you need to sign in, the server opens a browser on its computer.

Related MCP server: NowAIKit

ITSM work

Read incident, problem, change, and request records. Review history, inspect attachments, or count records for a status update.

For example:

  • "Show 10 active incidents assigned to the Service Desk group, ordered by priority."

  • "Summarize INC0012345, including comments and work notes from the last 30 days."

  • "Count open incidents by assignment group. Include the filters you used."

  • "Show the answers submitted with RITM0012345."

Use record numbers and group names from your instance. Include a time period and limit for lists and history.

Creating tickets, updating work notes, and changing assignments require write tools and ServiceNow permissions. See making changes.

Instance administration and development

Inspect configuration, investigate issues, and prepare changes. Start with a record name or a question. You do not need to know the MCP tool names.

Work

What you can inspect

Tables and fields

Field types, choice labels, references, and inherited fields.

Scripts

Business Rules, Script Includes, Client Scripts, and code-search matches.

Flow Designer

Flow and subflow triggers, inputs, outputs, and configured steps.

Troubleshooting

Recent errors, slow transactions, table health, and audit history.

Configuration management database (CMDB)

Configuration items, their relationships, and class metadata.

For example:

  • "Read the Business Rule named 'Validate priority'. Explain when it runs and what its script does."

  • "Find scripts that call gs.eventQueue. Show the matching records."

  • "Inspect the 'New starter' flow. Explain its trigger and configured steps."

  • "Investigate script errors from the last 24 hours. Show the evidence for each finding."

Replace example rule and flow names with names from your instance. Diagnostic findings help you investigate. They do not establish a root cause or repair the instance. The flow tool inspects configuration, checks saved V2 structure locally, and reads status. It cannot change or execute a flow.

With write tools enabled, you can create or update configuration records, including script fields. Follow the change workflow before applying a script change.

Connection setup

An administrator prepares OAuth. Each user authorizes access with their own ServiceNow account. Your AI app starts the server locally using stdio. You need Python 3.14 or later, uv, and an AI app that can start local MCP servers.

1. Prepare OAuth in ServiceNow

OAuth lets users authorize the connection in a browser. The public client ID identifies the application and is not a password or client secret.

Open System OAuth > Application Registry. Select New, then Create an OAuth API endpoint for external clients, or select an existing inbound application. Configure the application to meet these requirements:

Requirement

Value

Client type

Public, with no client secret

Authorization flow

Authorization code with PKCE

PKCE method

S256

Scope

useraccount

Redirect URL

http://127.0.0.1:8765/oauth/callback

Save the application and copy its public client ID. If you cannot configure OAuth, ask your administrator for the client ID and instance URL. Users still need API access and table and field permissions.

2. Add the connection to your AI app

Replace https://your-instance.service-now.com and your-public-client-id with the values from your administrator. Use the instance's HTTPS address without a page path such as /nav_to.do.

These examples select readonly and block writes with SERVICENOW_ENV=prod. The environment setting controls write protection. It does not select the instance or detect whether the instance is production.

Keep existing server entries when adding this configuration. Do not add passwords, API keys, client secrets, or tokens.

VS Code with GitHub Copilot, or Claude Code

Save this configuration as .mcp.json in the top-level folder you open in your AI app:

{
  "mcpServers": {
    "servicenow-platform": {
      "command": "uvx",
      "args": ["servicenow-platform-mcp"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_OAUTH_CLIENT_ID": "your-public-client-id",
        "MCP_TOOL_PACKAGE": "readonly",
        "SERVICENOW_ENV": "prod"
      }
    }
  }
}

In VS Code, open Chat and enable the ServiceNow tools. In Claude Code, approve the project MCP server when prompted. For user-wide configuration and connection controls, see the VS Code guide or Claude Code guide.

Add this to opencode.json in your project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servicenow-platform": {
      "type": "local",
      "command": ["uvx", "servicenow-platform-mcp"],
      "enabled": true,
      "environment": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_OAUTH_CLIENT_ID": "your-public-client-id",
        "MCP_TOOL_PACKAGE": "readonly",
        "SERVICENOW_ENV": "prod"
      }
    }
  }
}

Restart OpenCode. See its MCP guide for other configuration options.

For another local MCP app, use the command uvx servicenow-platform-mcp with the same four environment variables. Its configuration format may differ. The installation guide includes a server entry you can adapt.

3. Sign in and check access

  1. Restart your AI app or its ServiceNow MCP server after saving the configuration.

  2. Ask: "List the available ServiceNow tools."

  3. Ask: "Use ServiceNow to show one active incident. Include its number and short description."

  4. If prompted, sign in through the browser with the intended ServiceNow account.

A returned record confirms read access to that table. If you cannot read incidents, use a table your account can access. Tool discovery alone does not confirm a working connection.

Tokens stay in server memory by default. The server renews expired access tokens when possible. Optional SERVICENOW_OAUTH_CACHE=os stores only refresh tokens in the native OS credential store, so a new local process can reuse a previous login. See OAuth cache configuration.

Making changes

Start with a development or test instance. Ask your administrator to enable only the write tools you need and grant the corresponding ServiceNow permissions.

For example, MCP_TOOL_PACKAGE=query,describe,record_read,record_write enables record inspection and changes. Set SERVICENOW_ENV=dev for that non-production instance. Restart the server after changing the configuration.

Record, attachment, and catalog changes require a preview before apply_change. The server does not enforce human approval. Review each change before applying it:

  1. Ask the app to read the current record.

  2. Ask for a preview of the proposed change.

  3. Review the target instance, record, field values, and script differences.

  4. Tell the app to apply that preview only when you approve it.

  5. Check the result in ServiceNow. Test any changed behavior on the instance.

For a ticket update:

Preview adding this work note to INC0012345: "Waiting for the caller to confirm the fix." Show the proposed change and wait for my approval.

For a script update:

Read the Business Rule named 'Validate priority'. Suggest a correction and explain it. Show a preview with the complete replacement script. Wait for my approval before applying it.

The preview tools return single-use tokens. apply_change checks policy, authorization, and detectable state changes. Tokens expire after 300 seconds and disappear on restart. If the result is UNKNOWN_OUTCOME, read the target state before another preview. Do not automatically replay the operation.

The readonly package includes catalog browsing. Catalog changes require the service_catalog_write group. A preview does not simulate fulfillment or guarantee prices.

Script updates replace the complete field value. The server does not check JavaScript syntax. Review and test the script before relying on its behavior.

Set SERVICENOW_ENV=prod or production to block writes through this server. ServiceNow permissions still control record access. Tool selection and environment settings add local controls.

Choose the available tools

MCP_TOOL_PACKAGE controls which tools your AI app can call:

Package

Use

readonly

ITSM reads, metadata, attachments, investigations, audits, flows, code search, and CMDB inspection.

core_readonly

Only queries, table descriptions, and attachment reads.

full

All tools, including reviewed record, attachment, and catalog changes.

none

Only list_tool_packages, for checking that the server starts.

The package defaults to readonly and the environment defaults to prod. A package enables tools. It does not grant ServiceNow permissions. list_tool_packages lists available packages and groups, not the active package. For the full inventory and tool inputs, see the tool reference.

If something does not work

Problem

Next action

The AI app cannot start the server

Check Python, uv, the server command, and the two required ServiceNow settings.

No browser opens, or authorization times out

Use a browser on the server's computer. Check the exact registered redirect URL.

ServiceNow rejects OAuth

Ask the administrator to check public-client mode, PKCE S256, client ID, scope, and redirect URL.

Sign-in works, but a record request returns 401 or 403

Ask the administrator to check API policies, roles, and record or field access rules.

Tools are missing or settings did not change

Check MCP_TOOL_PACKAGE and restart the MCP server.

For a failed request, include the action, record or table, and sanitized error in your report. Exclude passwords, tokens, raw headers, and browser callback URLs. See installation troubleshooting for more detailed checks.

ServiceNow data returned by tools becomes available to your AI app. Use an app approved for the data you handle.

More help

Report an issue · PyPI package · MIT license

Available Tools

15 tools
analysisA

Run bounded, read-only analysis over catalog answers or journals.

Args: action: 'ritm_variables' | 'journal_history' | 'describe'. table: Target table for journal_history. sys_id: Target record sys_id for ritm_variables or journal_history. fields_csv: Allowed journal fields: comments, work_notes, close_notes. since: ISO date floor for journal_history; overrides window_days. window_days: Journal window; defaults to 90 days. limit: Row cap; defaults to MAX_ROW_LIMIT and is capped by it. offset: Zero-based row offset.

Inputs: action (required), limit, since, table, +4 more. Returns: result

attachmentA

Read attachments. action: 'list' | 'get' | 'download' | 'download_by_name'.

Args: action: One of: list, get, download, download_by_name. sys_id: Attachment sys_id (for get, download). table: Parent table (for list, download_by_name). table_sys_id: Parent record sys_id (for list, download_by_name). file_name: File name (for download_by_name).

Inputs: action (required), table, sys_id, file_name, +1 more. Returns: result

attachment_writeA

Write attachments. action: 'upload' | 'delete'.

Args: action: 'upload' or 'delete'. table: Parent table (upload). table_sys_id: Parent record sys_id (upload). file_name: Attachment file name (upload). content_base64: Base64-encoded file bytes (upload). content_type: MIME type (upload, default 'application/octet-stream'). sys_id: Attachment sys_id (delete).

Inputs: action (required), table, sys_id, file_name, +3 more. Returns: result

auditA

Inspect ServiceNow audit posture (table/field config) and audit trail.

IMPORTANT: sys_audit is one of the largest tables on the platform. Every action keeps a default 90-day window for that reason. Override window_days (or since on history) only when you genuinely need older rows - wider windows cause slow queries and can time out.

Args: action: 'check_field' | 'check_fields' | 'check_table' | 'history' | 'describe'. table: ServiceNow table name (required for all actions except 'describe'). field: Field name (required for 'check_field'). fields_csv: Comma-separated field names (required for 'check_fields', 1..50). sys_id: 32-char record sys_id (required for 'history'). since: YYYY-MM-DD cutoff (history only; overrides window_days). window_days: Audit-trail/positive-control window (defaults to 90). limit: Row cap for 'history' (defaults to settings.max_row_limit).

Inputs: action (required), field, limit, since, +4 more. Returns: result

code_searchA

Search ServiceNow code or inspect Code Search table coverage.

Args: action: One of 'search', 'list_tables', or 'describe'. term: Search term for action='search'. table: Optional table filter for action='search' (e.g. 'sys_script_include'). search_group: ServiceNow Code Search group; empty uses sn_codesearch.Default Search Group. limit: Max search results for action='search'. Default 20. extended_matching: Include additional Code Search context fields. Default false. Set true when the extra context is needed.

Inputs: term, limit, table, action, +2 more. Returns: result

describeA

Return slim field metadata for a table, or list tables / script fields.

Args: table: ServiceNow table name. Required for the default flow and for action='list_script_fields'. Ignored by action='list_tables'. fields: Comma-separated fields to include. Empty returns a bounded compact page. '*' explicitly returns all fields. verbose: When True, return the full sys_dictionary row per field minus a fixed deny-list of high-noise keys. Default False. include_docs: When True, attach the matching sys_documentation entry (label/help/hint/url) per field. Default False. action: When 'list_script_fields', return the dictionary-driven script-bearing fields for table with its resolved super_class chain. When 'list_tables', list tables from sys_db_object (optionally filtered by name_filter). Empty (default) runs the standard table-describe flow. name_filter: Substring matched against table name and label when action='list_tables'. Empty returns all tables (capped). field_offset: Zero-based field offset for compact default pages. field_limit: Field count for compact default pages (1-100).

Inputs: table, action, fields, verbose, +4 more. Returns: result

flowA

Inspect Flow Designer flows, triggers, and value blobs (read-only).

Args: action: 'contract' | 'inspect' | 'find_by_table' | 'decode_values' | 'list_triggers' | 'describe'. sys_id: Flow sys_id (contract/inspect; mutually exclusive with name). name: Flow name (contract/inspect; mutually exclusive with sys_id). value: gzip+base64+JSON blob to decode (decode_values). table: Target table (find_by_table; optional filter for list_triggers). trigger_type: Trigger type filter (list_triggers, e.g. 'record_update'). active: 'true' | 'false' filter (list_triggers). limit: Row cap for list_triggers (default 100). sections: Comma-separated inspect/contract sections. Empty uses the compact default; '*' returns all. section_limit: Shared cap for selected flow rows/nodes (default 100, max MAX_ROW_LIMIT).

Inputs: action (required), name, limit, table, +6 more. Returns: result

investigateA

Run an investigation or explain a finding.

Args: action: 'run' | 'explain' | 'describe'. name: Investigation name (required for 'run'; optional direct selector for 'explain' and filter for 'describe'). Available: stale_automations, deprecated_apis, table_health, acl_conflicts, error_analysis, slow_transactions, performance_bottlenecks. params: JSON string of run parameters (run only). element_id: 'table:sys_id' identifier of a finding (explain only).

Inputs: action (required), name, params, element_id. Returns: result

list_tool_packagesA

List all available tool packages and their tool groups.

Inputs: no named parameters. Returns: result

queryA

Read records, aggregates, or a single record from any ServiceNow table.

Args: table: ServiceNow table name (e.g. 'incident'). sys_id: When set, fetch a single record by sys_id (other filter args ignored except fields and display_values). encoded_query: ServiceNow encoded query string (e.g. 'state=1^priority=2'). Empty = no filter. fields: Comma-separated field projection. List mode requires this argument. '*' explicitly requests all masked fields. Exact sys_id mode defaults to the compact sys_id,sys_updated_on projection. limit: Max rows (1-max_row_limit). Default 20. offset: Pagination offset. order_by: Field name; prefix with '-' for descending (e.g. '-sys_created_on'). display_values: True returns display_value form for reference and choice fields. aggregate: Comma-separated aggregations: 'count', 'avg:', 'sum:', 'min:', 'max:'. When set, returns aggregate result instead of rows. group_by: Comma-separated fields to group by, e.g. state,active (aggregate mode only). resolve_labels: Comma-separated 'field=label' pairs (e.g. 'state=open,priority=high'). Each label is resolved via ChoiceRegistry to its underlying value, then ANDed into encoded_query as 'field=value'.

Inputs: table (required), limit, fields, offset, +7 more. Returns: result

record_applyA

Commit a previously previewed write. Single-use token.

Args: preview_token: The token returned by record_write in preview mode. Single-use - consumed on success or failure.

Inputs: preview_token (required). Returns: result

record_readA

Fetch a record by sys_id or name from any table.

Exactly one of sys_id or name must be supplied. Sensitive fields are masked. The response includes a script_fields list (resolved dynamically via sys_dictionary plus the table's super_class chain) so callers can discover which script-bearing fields are writable on a subsequent record_write.

Args: table: ServiceNow table name (e.g. sys_script, catalog_script_client, incident). Tables with zero script fields return script_fields: [] and succeed. sys_id: Mutually exclusive with name. Direct lookup by sys_id. name: Mutually exclusive with sys_id. Resolves via name=<value> query; ambiguous matches return an error. fields: Comma-separated field projection. Empty returns compact identity/update metadata plus all discovered script-bearing fields. '*' returns the full masked record.

Inputs: table (required), name, fields, sys_id. Returns: result

record_writeA

Create, update, or delete a record. Defaults to preview mode.

Supply all field values, including complete script or markup strings, in data. Omitted fields stay unchanged on update. Dictionary metadata identifies supplied XML fields, including inherited fields; malformed XML is rejected before preview creation or mutation. Creates also check inherited mandatory fields, with child declarations taking precedence. Metadata request errors block writes.

Args: action: 'create' | 'update' | 'delete'. table: Target table. Required. sys_id: Required for 'update' and 'delete'. data: JSON string mapping field names to values, including any script fields. Required for 'create' and 'update'. Maximum 256 KiB of UTF-8 JSON, including escaping and field names. preview: When True (default) returns a preview_token; caller invokes record_apply to commit. When False, write commits immediately.

Inputs: action (required), data, table, sys_id, +1 more. Returns: result

resolve_choiceA

Resolve a choice label to its underlying value via ChoiceRegistry.

Args: table: ServiceNow table name. field: Field name on that table. label: Choice label to resolve. When empty, returns the full {label: value} mapping for the field.

Inputs: field (required), table (required), label. Returns: result

service_catalogB

Service Catalog operations. Dispatch on action.

Args: action: One of: catalogs_list, catalog_get, categories_list, category_get, items_list, item_get, item_variables, order_now, add_to_cart, cart_get, cart_submit, cart_checkout. sys_id: Record sys_id (catalog_get, category_get, item_get, item_variables). item_sys_id: Catalog item sys_id (order_now, add_to_cart). catalog_sys_id: Catalog sys_id (categories_list). catalog: Filter by catalog sys_id (items_list). category: Filter by category sys_id (items_list). text: Search text (catalogs_list, items_list). variables: JSON object of variable name/value pairs (order_now, add_to_cart). limit: Max results (catalogs_list, categories_list, items_list). Default 20. offset: Pagination offset (categories_list, items_list). Default 0. top_level_only: Return only top-level categories (categories_list).

Inputs: action (required), text, limit, offset, +7 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.6/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have distinct purposes, but `query` and `record_read` overlap in single-record fetching, and `attachment` vs `attachment_write` require careful reading to distinguish read vs write operations. Descriptions otherwise clarify boundaries well.

    Naming Consistency2/5

    Naming is mixed: some tools use verb_noun (`record_write`, `attachment_write`, `list_tool_packages`), while others are bare nouns (`attachment`, `flow`, `audit`) or bare verbs (`query`, `investigate`, `describe`). Many tools are action-dispatch style with a single name, creating inconsistent patterns.

    Tool Count4/5

    15 tools is at the upper end of the ideal range, but the broad ServiceNow platform scope (records, attachments, catalog, flows, audit, code search, analysis) justifies each tool's existence. No obvious bloat or missing core utility.

    Completeness4/5

    The surface covers CRUD for records, attachments, catalog operations, flow inspection, audit checks, and code search. Minor gaps exist (e.g., no update/delete for attachments besides upload/delete, no flow modification), but the core workflows are well covered.

    Maintenance

    ActivityActive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers