servicenow_aggregate
Compute server-side aggregates (count, avg, min, max, sum) over a table via the Stats API, with optional grouping. Avoids pulling individual rows.
LABSCO SUMMARY
Full Table API reach over an instance, with the writes previewing themselves first.
The read half is the reason to wire it up: any table, encoded queries, server-side aggregates, and column definitions straight out of sys_dictionary — plus the ability to ask which restricted tables the connected user can actually reach before an agent plans around them. Writes are there too, and since 2.0 they answer with a preview until a call explicitly passes apply: true.
What it is
An MCP server over a ServiceNow instance's REST APIs: Table, Aggregate, Attachment, Import Set, Batch and CMDB, plus the Service Catalog, Change Management and Knowledge plugin APIs. Since 2.0 the record-write tools return a non-mutating preview unless the call passes apply: true.
What you get
- Any table, read properly:
servicenow_query_tablewith encoded queries, field selection and pagination, andservicenow_get_recordby sys_id - Writes with the preview default —
servicenow_create_record,servicenow_update_record,servicenow_delete_record - Schema without opening the platform UI:
servicenow_list_tablesfromsys_db_object,servicenow_describe_tablefromsys_dictionarywith type, mandatory and reference per column - Aggregates computed server-side rather than paged back —
servicenow_aggregatedoes count, avg, min, max and sum with optional grouping - Attachments listed, read, uploaded as base64 and deleted:
servicenow_list_attachments,servicenow_download_attachment,servicenow_upload_attachment,servicenow_delete_attachment - Several instances side by side —
servicenow_list_instances,servicenow_use_instance, andservicenow_set_credentialsto change the connection at runtime - A preflight pair worth running first:
servicenow_test_connectionreads onesys_userrecord and reports status and latency,servicenow_check_capabilitiesreports which admin-restrictedsys_*tables your user can actually read - More packages behind
SN_TOOL_PACKAGES— script intelligence,servicenow_where_usedfor every script and ACL touching a field,servicenow_trace_table_eventfor what runs on save, code checking and ATF. The default profile iscore;allenables everything
Requirements
A ServiceNow instance and credentials for it. SN_INSTANCE is the host — dev12345.service-now.com — and the quickest path is Basic auth with SN_USER and SN_PASSWORD. For anything long-lived, npx servicenow-mcp-ai login runs the one-time OAuth 2.1 flow with PKCE and stores a refresh token instead of the password; API key via SN_API_KEY and a pre-obtained bearer token are also supported. Node.js 20 or newer. Run it as npx -y servicenow-mcp-ai over stdio; credentials resolve from SN_ENV_FILE, then ~/.config/servicenow-mcp-ai/.env, then the project .env, with real environment variables taking precedence.
Setup effort
One command plus credentials — npx servicenow-mcp-ai, then supply credentials
USE CASES
01
Finding out what an agent can reach on a new instance
Verify the credentials against one record, then preview which restricted tables the connected user can read.
02
Answering a reporting question without exporting rows
Compute the counts and averages server-side with grouping instead of paging every record back.
03
Working with a table nobody has documented
List the tables matching a name fragment, then read the columns with their types and references.
04
Attaching evidence to a ticket
Read the record, upload the file against it, then confirm what is now attached.
05
Switching between a sandbox and the live instance
List the configured profiles, then switch the active one — tokens and cached schema are scoped per identity.
19 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
servicenow_check_capabilities
Preflight which admin-restricted sys_* tables the connected user can actually read, and report which higher-level capabilities (schema reads, script intelligence, ACL audit) are achievable. Run this before relying on the scripts/flows/codecheck tools on a governed instance — on a least-privilege account those reads may be silently empty.
servicenow_create_record
Create a new record in a table with the given field values.
servicenow_delete_attachment
Delete an attachment by its sys_id.
servicenow_delete_record
Delete a record from a table by its sys_id.
servicenow_describe_table
List a table's columns (name, label, type, mandatory, reference) from sys_dictionary.
servicenow_download_attachment
Download an attachment's bytes, returned as base64. Large files are refused (see SN_MAX_RESULT_CHARS).
servicenow_get_attachment
Read a single attachment's metadata by its sys_id.
servicenow_get_record
Read a single record from a table by its sys_id.
servicenow_get_status
Show the configured instance, user, auth mode and access policy, and whether credentials are complete. The password is never revealed.
servicenow_list_attachments
List attachment metadata, optionally scoped to a specific record (table + sys_id).
servicenow_list_instances
List the configured ServiceNow connection profiles (instances): name, host, user, read-only flag and whether credentials are complete. Passwords are never included.
servicenow_list_tables
List tables from sys_db_object, optionally filtered by a name or label fragment.
servicenow_query_table
Read records from any ServiceNow table through the Table API. Supports encoded queries, field selection and pagination.
servicenow_set_credentials
Save or update the ServiceNow connection credentials. Values are persisted to the env file and used for all subsequent requests. Provide any subset of fields.
servicenow_test_connection
Verify that the configured credentials actually work: reads one sys_user record and reports ok/status/latency. Auth and connectivity problems are returned structurally (ok:false), not as errors.
servicenow_update_record
Update fields on an existing record identified by its sys_id.
servicenow_upload_attachment
Attach a file (provided as base64) to a record identified by table + sys_id.
servicenow_use_instance
Switch the active ServiceNow connection profile (persisted to the env file). All identity-scoped caches (OAuth tokens, schema, plugin availability) are cleared.
BEFORE YOU INSTALL
What to know first
Tools you get
19 tools when we connected; the project documents 67. SN_TOOL_PACKAGES defaults to core (table, schema, aggregate, attachment) plus six admin tools. Set SN_TOOL_PACKAGES=all for all 67, including write tools such as create_change and send_email.
Requires
- npx on PATH
- Node.js 20+
- SN_INSTANCE in your environment
- One way to sign in to that instance: SN_USER and SN_PASSWORD (Basic auth), a refresh token stored by npx servicenow-mcp-ai login (OAuth), SN_API_KEY, or SN_BEARER_TOKEN
INSTALLATION
Connect your client
Server setup
TERMINAL
npx servicenow-mcp-aiMCP Clients
Claude Desktop, Any MCP client
JSON
{
"mcpServers": {
"servicenow": {
"command": "npx",
"args": [
"-y",
"servicenow-mcp-ai"
]
}
}
}Claude Code — plugin
CLAUDE CODE — PLUGIN · IN CLIENT
/plugin marketplace add IvanBBaev/servicenow-mcp-ai
/plugin install servicenow-mcp-aiVS Code — extension
VS CODE — EXTENSION · TERMINAL
code --install-extension ivanbbaev.servicenow-mcp-ai
