servicenow-mcp-ai

# servicenow-mcp-ai — ServiceNow MCP Server

📖 **[Documentation site →](https://leasstatt.github.io/servicenow-mcp-ai/)**

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an
MCP client (VS Code, Claude Desktop, etc.) run commands against a **ServiceNow**
instance through its REST APIs — Table, Aggregate, Attachment, Import Set, Batch
and CMDB, plus the Service Catalog, Change Management and Knowledge plugin APIs.
Credentials are kept in a local env file and can be updated at runtime through a tool.

**Contents:** [Features](#features) · [Requirements](#requirements) ·
[Setup](#setup) · [Configure credentials](#configure-credentials) ·
[Run / debug](#run--debug) · [Develop](#develop) · [Tools](#tools) ·
[Resources](#resources) · [Prompts](#prompts) ·
[Project structure](#project-structure) · [Security notes](#security-notes) ·
[Project documentation](#project-documentation)

## Features

- Full **Table API**: query, read, create, update and delete records on **any**
  table, with encoded queries, field selection and pagination.
- Extra ServiceNow APIs: **Aggregate** (Stats), **Attachment**
  (list/upload/download/delete), **Import Set**, **Batch** (many REST calls in a
  single request), plus table/column **metadata** (`sys_db_object`,
  `sys_dictionary`).
- Process & plugin APIs: **CMDB** (class-aware CI CRUD + meta via IRE),
  **Service Catalog** (browse/order items), **Change Management** (typed
  creation + conflict detection) and **Knowledge** (article search).
  Plugin-scoped APIs report clearly when not active on the instance.
- **Script intelligence**: read and search the instance's own code (business
  rules, script includes, client scripts, UI policies/actions, scheduled jobs,
  transform/REST scripts, ACLs) and get a table's full automation picture — all
  read-only over the Table API.
- **Flow tracing & code checking** (Phase 8): deterministically trace what a
  table operation runs (`flows` package — business rules, flows, workflows and
  notifications, in order, with a Mermaid flowchart), read Flow Designer flows
  and run history, and lint scripts against a local rule set with an aggregate
  code-health report (`codecheck`). Run ATF tests via the CI/CD API (`atf`,
  opt-in, non-default — the run tools execute on the instance).
- **Self-documentation**: a local Markdown knowledge base (read/write/search) plus
  deterministic Mermaid generators (ER diagrams from references, record-lifecycle
  flowcharts from business rules) so the server builds durable, reusable context.
- **Prompts**: ready-made workflows (incident triage, change impact analysis,
  document a table) that orchestrate the tools.
- **Tool packages**: load only the tool groups you need via `SN_TOOL_PACKAGES`
  (default profile `core`; `all` enables everything).
- **Basic** or **OAuth 2.0** authentication over HTTPS; the password/token is
  never echoed back.
- Least-privilege controls: table allow/deny lists and a global read-only mode.
- Resilience: per-request timeout, retry with backoff and `Retry-After`, SSRF
  guard, and a result-size guard.
- MCP **tool annotations** and **resources**, structured error payloads, and
  structured logging on stderr.
- Credentials in an env file (project, `~/.config`, or `SN_ENV_FILE`), updatable
  at runtime via `servicenow_set_credentials`.

## Requirements

- Node.js 20+ (enforced: `engines` + a runtime guard with a clear message;
  the project targets the version in `.nvmrc`).

## Setup

From source (for development):

```bash
npm install
npm run build
```

Or run the published package directly, without cloning:

```bash
npx servicenow-mcp-ai
```

Register it with an MCP client (Claude Desktop, VS Code Chat, the Inspector…) by
pointing the server command at `npx`:

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["-y", "servicenow-mcp-ai"]
    }
  }
}
```

Credentials are read from `~/.config/servicenow-mcp-ai/.env` (or real environment
variables) — see below.

## Configure credentials

Credentials live in `.env` at the project root (git-ignored):

```dotenv
SN_INSTANCE=your-instance.service-now.com
SN_USER=your.username@example.com
SN_PASSWORD=your-password
```

`SN_INSTANCE` accepts `dev12345`, `dev12345.service-now.com` or a full `https://` URL.

You can also set or change them at runtime by calling the
`servicenow_set_credentials` tool — the new values are written straight back to the env file.

The env file is resolved in this order: `SN_ENV_FILE`, then
`~/.config/servicenow-mcp-ai/.env` (XDG) if present, then the project-root `.env`.
A global/`npx` install therefore writes to your user config rather than into
`node_modules`. Real environment variables always take precedence over the file.

### OAuth 2.1 (Authorization Code + PKCE) — recommended

Register an **Authorization Code** OAuth API endpoint in ServiceNow with a
loopback redirect URL (e.g. `http://localhost:53682/callback`), set
`SN_OAUTH_CLIENT_ID` (and `SN_OAUTH_CLIENT_SECRET` for a confidential client),
then run the one-time interactive login:

```bash
npx servicenow-mcp-ai login
```

It opens the browser, you approve, and the obtained **refresh token** is stored
in your env file. The server then runs non-interactively (refresh_token grant) —
no password is ever stored. PKCE (S256) is always used.

> The OAuth 2.0 **password grant (ROPC) is deprecated** in OAuth 2.1 and disabled
> on many instances; prefer `login`. `client_credentials` and `refresh_token`
> grants remain supported for service accounts. See [.env.example](.env.example).

### Supported authentication methods

Every inbound REST auth method ServiceNow offers is covered:

| Method | `SN_AUTH` | Set | Notes |
| ------ | --------- | --- | ----- |
| Basic | `basic` | `SN_USER` / `SN_PASSWORD` | Default. |
| OAuth 2.1 — Authorization Code + PKCE | `oauth` | `npx servicenow-mcp-ai login` | **Recommended.** Interactive, stores a refresh token. |
| OAuth — Client Credentials | `oauth` | `SN_OAUTH_GRANT=client_credentials` | Service-to-service. |
| OAuth — Refresh Token | `oauth` | `SN_OAUTH_GRANT=refresh_token` + `SN_OAUTH_REFRESH_TOKEN` | Set by `login`. |
| OAuth — JWT Bearer | `oauth` | `SN_OAUTH_GRANT=jwt_bearer` + `SN_OAUTH_JWT_KEY` | RS256 assertion; no password. |
| OAuth — Password (ROPC) | `oauth` | `SN_OAUTH_GRANT=password` | **Deprecated.** |
| API Key | `apikey` | `SN_API_KEY` | `x-sn-apikey` header. |
| Bearer token | `token` | `SN_BEARER_TOKEN` | Pre-obtained token, used verbatim. |
| Mutual TLS (client cert) | `none` (or layered) | `SN_TLS_CLIENT_CERT` / `_KEY` | Cert maps to a user; needs optional `undici`. |

### Environment variables

All settings are read from `.env` (or the real process environment, which takes
precedence). Only the first three are required; the rest are optional tuning knobs.
See [.env.example](.env.example) for a template.

| Variable                 | Required | Default         | Description                                                                                                                                                                                                                                                                |
| ------------------------ | :------: | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SN_INSTANCE`            |   yes    | —               | Instance name, host, or `https://` URL (`dev12345`, `dev12345.service-now.com`).                                                                                                                                                                                           |
| `SN_USER`                |   yes    | —               | ServiceNow username for Basic auth.                                                                                                                                                                                                                                        |
| `SN_PASSWORD`            |   yes    | —               | ServiceNow password. Never logged or returned by any tool.                                                                                                                                                                                                                 |
| `SN_TIMEOUT_MS`          |    no    | `30000`         | Per-request timeout in milliseconds.                                                                                                                                                                                                                                       |
| `SN_MAX_RETRIES`         |    no    | `2`             | Retries for transient failures (429/5xx, network errors). Non-idempotent writes are only retried on connect errors.                                                                                                                                                        |
| `SN_MAX_RECORDS`         |    no    | `10000`         | Hard cap on records returned by a `fetchAll` query.                                                                                                                                                                                                                        |
| `SN_MAX_RESULT_CHARS`    |    no    | `100000`        | Character budget for a query result before it is truncated for the client.                                                                                                                                                                                                 |
| `SN_ALLOWED_HOSTS`       |    no    | —               | Comma-separated allow-list of permitted hosts (for custom or sovereign-cloud domains). When set, only