# servicenow-mcp-server

A complete [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for ServiceNow. Connect Claude (or any MCP client) to your ServiceNow instance and interact with incidents, changes, CMDB, service catalog, users, groups, and the knowledge base using natural language.

---

## Authentication

Three auth methods are supported. Set the env vars for exactly one — the server detects which to use automatically.

| Method | Env vars required | Best for |
|--------|------------------|----------|
| [OAuth 2.0 PKCE](#option-a--oauth-20-pkce-recommended) | `SERVICENOW_CLIENT_ID` + `SERVICENOW_CLIENT_SECRET` | SSO / per-user permissions |
| [Basic auth](#option-b--basic-auth) | `SERVICENOW_USERNAME` + `SERVICENOW_PASSWORD` | Dev / service accounts |
| [Static token](#option-c--static-bearer-token) | `SERVICENOW_ACCESS_TOKEN` | Quick testing |

**Priority (if multiple are set):** static token → basic → OAuth PKCE

---

## Option A — OAuth 2.0 PKCE (recommended)

The PKCE flow authenticates as the real user. Each person who runs the server logs in via your SSO identity provider and gets access only to what their ServiceNow roles permit — admins can do admin things, itil users are limited to itil operations, and so on.

### 1. Create an OAuth application in ServiceNow

> **System OAuth → Application Registry → New → "Create an OAuth API endpoint for external clients"**

- Set **Redirect URL** to `http://localhost:54321/callback`
- Copy the **Client ID** and **Client Secret**

If you need a different callback port, set `SERVICENOW_OAUTH_CALLBACK_PORT` (default: `54321`) and update the redirect URL in ServiceNow to match.

### 2. Configure your env vars

```bash
SERVICENOW_INSTANCE_URL=https://yourcompany.service-now.com
SERVICENOW_CLIENT_ID=your_client_id
SERVICENOW_CLIENT_SECRET=your_client_secret

# Optional — only needed if port 54321 is taken
# SERVICENOW_OAUTH_CALLBACK_PORT=54321
```

### 3. First-time login

**Before adding to Claude Desktop**, run the server once in a terminal to complete the browser login:

```bash
npx @autopilot715/servicenow-mcp-server
```

Your browser will open to your ServiceNow login (which will trigger SSO if configured). After authenticating, tokens are cached at `~/.config/servicenow-mcp-server/tokens.json`. The server starts and you can Ctrl+C once you see it's running.

Subsequent starts (including from Claude Desktop) are silent — the cached token is used and refreshed automatically. A full re-login only happens if the refresh token expires or is revoked.

### 4. Add to Claude Desktop config

**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["@autopilot715/servicenow-mcp-server"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourcompany.service-now.com",
        "SERVICENOW_CLIENT_ID": "your_client_id",
        "SERVICENOW_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

Restart Claude Desktop after editing the config.

---

## Option B — Basic auth

Simplest to set up. Use a dedicated service account in production rather than a personal login.

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["@autopilot715/servicenow-mcp-server"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourcompany.service-now.com",
        "SERVICENOW_USERNAME": "your_username",
        "SERVICENOW_PASSWORD": "your_password"
      }
    }
  }
}
```

---

## Option C — Static bearer token

Use an existing OAuth token. Tokens expire and require manual renewal.

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "npx",
      "args": ["@autopilot715/servicenow-mcp-server"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://yourcompany.service-now.com",
        "SERVICENOW_ACCESS_TOKEN": "your_oauth_token"
      }
    }
  }
}
```

> Tokens can be found or generated at **System OAuth → Manage Tokens** in ServiceNow.

---

## Running Locally (from source)

```bash
git clone https://github.com/kylburns89/servicenow-mcp-server.git
cd servicenow-mcp-server
npm install
npm run build
```

Copy `.env.example` to `.env` and fill in your credentials:

```bash
cp .env.example .env
```

Then start with:

```bash
# Node 20+ (recommended)
node --env-file=.env dist/index.js

# Node 18
export $(grep -v '^#' .env | xargs) && node dist/index.js
```

For active development, run the TypeScript compiler in watch mode in one terminal and restart the server after each save:

```bash
npm run dev   # tsc --watch
```

---

## Example Prompts

Once connected, you can use natural language:

- *"Show me all P1 and P2 incidents assigned to the Network Operations group"*
- *"Create an incident for a login issue reported by jdoe@company.com, category software, high priority"*
- *"List all emergency change requests scheduled this week"*
- *"Find all servers in the Data Center that are in maintenance status"*
- *"Search the knowledge base for articles about VPN setup"*
- *"Get the full details for change request CHG0012345"*
- *"Add a work note to INC0001234 saying the server has been rebooted and is under monitoring"*
- *"Who are the members of the Service Desk group?"*

---

## Tools (41 total)

### Generic Table API
| Tool | Description |
|------|-------------|
| `servicenow_query_records` | Query any table with encoded filters and pagination |
| `servicenow_get_record` | Get a single record by sys_id |
| `servicenow_create_record` | Create a record in any table |
| `servicenow_update_record` | Update a record by sys_id (PATCH) |
| `servicenow_delete_record` | Delete a record by sys_id ⚠️ |

### Incidents
| Tool | Description |
|------|-------------|
| `servicenow_list_incidents` | List/search incidents with filters |
| `servicenow_get_incident` | Get incident by number (INC...) or sys_id |
| `servicenow_create_incident` | Create a new incident |
| `servicenow_update_incident` | Update state, assignment, priority, etc. |
| `servicenow_add_work_note` | Add a work note or comment to any record |

### Change Management
| Tool | Description |
|------|-------------|
| `servicenow_list_changes` | List/search change requests |
| `servicenow_get_change` | Get change by number (CHG...) or sys_id |
| `servicenow_create_change` | Create a change request |
| `servicenow_update_change` | Update state, plans, assignment |

### Users & Groups
| Tool | Description |
|------|-------------|
| `servicenow_list_users` | Search users |
| `servicenow_get_user` | Get user by username, email, or sys_id |
| `servicenow_list_groups` | List user groups |
| `servicenow_get_group_members` | Get all members of a group |

### CMDB
| Tool | Description |
|------|-------------|
| `servicenow_search_ci` | Search CIs by name, class, or location |
| `servicenow_get_ci` | Get full CI details |
| `servicenow_get_ci_relationships` | Traverse upstream/downstream CI relationships (configurable depth) |

### Service Catalog
| Tool | Description |
|------|-------------|
| `servicenow_list_catalog_items` | Browse catalog items |
| `servicenow_get_catalog_item` | Get item details and required variables |
| `servicenow_submit_catalog_request` | Submit a catalog request |
| `servicenow_list_sc_requests` | List catalog requests (REQ...) |

### Knowledge Base
| Tool | Description |
|------|-------------|
| `servicenow_search_knowledge` | Search KB articles |
| `servicenow_get_kb_article` | Get full article content |

### Bulk Operations
| Tool | Description |
|------|-------------|
| `servicenow_bulk_update` | Update multiple records matching a query (dry-run by default) ⚠️ |
| `servicenow_bulk_delete` | Delete multiple records matching a query (dry-run by default) ⚠️ |

### Attachments
| Tool | Description |
|------|-------------|
| `servicenow_list_attachments` | List file attachments for a record |
| `servicenow_get_attachment_content` | Download attachment content (text inline, binary via URL) |
| `servicenow_upload_attachment` | Upload a file attachment to any record |

### Developer & Admin
| Tool | Description |
|------|-------------|
| `servicenow_aggregate` | COUNT/SUM/AVG/MIN/MAX on any table, with optional grouping |
| `servicenow_get_table_schema` | Introspect field definitions from sys_dictionary |
| `servicenow_get_instance_info` | Instance version, cluster nodes, and upgrade history |
| `servicenow_query_logs` | Query syslog for errors, warnings, and debug messages |
| `servicenow_search_artifacts` | Search code across business rules, script includes, client scripts, UI actions, and scripted REST ops |
| `servicenow_list_applications` | List installed scoped applications |
| `servicenow_discover_tables` | Search and browse the table catalog (sys_db_object) |
| `servicenow_list_atf_tests` | List ATF tests and test suites |
| `servicenow_run_atf_test` | Execute an ATF test or suite via the ATF REST API |

---

## Query Syntax Reference

ServiceNow encoded query syntax for the `query` parameters:

| Operator | Example | Meaning |
|----------|---------|---------|
| `=` | `state=1` | Equals |
| `!=` | `state!=7` | Not equals |
| `>=` | `priority>=2` | Greater than or equal |
| `LIKE` | `nameLIKEjohn` | Contains |
| `^` | `state=1^priority=1` | AND |
| `^OR` | `state=1^ORstate=2` | OR |
| `javascript:` | `assigned_to=javascript:gs.getUserID()` | Script expression |
| `STARTSWITH` | `numberSTARTSWITHINC` | Starts with |

---

## Project Structure

```
src/
├── index.ts                       # Entry point, server init, transport selection
├── types.ts                       # TypeScript interfaces and field resolvers
├── constants.ts                   # Table names, state labels, limits
├── schemas/common.ts              # Shared Zod schemas
├── services/
│   ├── auth.ts                    # Auth mode detection, OAuth PKCE flow, token cache
│   └── servicenow-client.ts       # Axios client, Table API helpers
└── tools/
    ├── table.ts       # Generic CRUD tools
    ├── incidents.ts   # Incident tools
    ├── changes.ts     # Change management tools
    ├── users.ts       # User & group tools
    ├── cmdb.ts        # CMDB + CI relationship traversal tools
    ├── catalog.ts     # Service catalog tools
    ├── knowledge.ts   # Knowledge base tools
    ├── bulk.ts        # Bulk update/delete with dry-run
    ├── attachments.ts # Attachment list/upload/download
    └── developer.ts   # Aggregations, schema, logs, artifact search, ATF, app/table discovery
```

---

## Contributing

Issues and PRs welcome on [GitHub](https://github.com/kylburns89/servicenow-mcp-server).

## License

MIT