# ServiceNow MCP Server

MCP server that gives Claude Code tools to read, write, and configure a ServiceNow instance.

## 🔧 Flow Designer — hands-off flow build

This server can **build, compile, and publish Flow Designer flows programmatically** — no browser, no UI "Activate", any scope — via the undocumented `processflow` API plus the CSRF `g_ck` header (the missing piece that makes basic auth work). Tools: `flow_designer_get` / `flow_designer_save` / `flow_designer_compile` (only basic-auth admin creds needed — no Script Runner).

➡️ **See [`docs/flow-designer/`](docs/flow-designer/README.md)** for the full kit: the recipe, the bundled `servicenow-flow-creator` skill, the gotchas, and a worked catalog-item example.

## Setup

### 1. Install and build

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

### 2. Configure credentials

Credentials are passed to the server through the **MCP config `env` block** (step 4). The code reads `process.env` only — there is **no `.env` loading**, so a `.env` file is ignored. You need three values:

- `SN_INSTANCE` — your instance **subdomain only** (e.g. `dev12345`, *not* the full `https://…` URL)
- `SN_USERNAME` — an admin user
- `SN_PASSWORD` — that user's password

> The flow-designer kit (`flow_designer_*`) and every `table_*` tool need only these basic-auth admin creds — **no Script Runner** (step 3 is optional).

### 3. (Optional) Deploy Script Runner — only for the `run_script` tool

> **Flow-designer users can skip this entirely.** `flow_designer_get/save/compile` and every `table_*` tool work with just the basic-auth admin creds from step 2. Script Runner is required **only** if you want the `run_script` tool (arbitrary server-side GlideScript).

To enable `run_script`, deploy a Scripted REST API app to your PDI:

1. Open ServiceNow Studio on your PDI
2. Create a new scoped app: scope = `x_mcp_snc`, name = "MCP Script Runner"
3. Create a Scripted REST API: name = `script_runner`
4. Add a POST resource at `/execute` with this script:

```javascript
(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
    var body = request.body.data;
    var script = '' + body.script;

    var evaluator = new GlideScopedEvaluator();
    evaluator.putVariable('request', request);
    evaluator.putVariable('response', response);

    var result;
    try {
        var gr = new GlideRecord('sys_script_include');
        gr.initialize();
        gr.setValue('script', script);
        result = evaluator.evaluateScript(gr, 'script', null);

        if (result !== null && result !== undefined) {
            response.setBody({ result: '' + result });
        }
    } catch (e) {
        response.setStatus(500);
        response.setBody({ error: '' + e });
        return;
    }
})(request, response);
```

**Note:** `GlideScopedEvaluator` allows injecting `request` and `response` into the script scope, so scripts CAN use `response.setBody()` directly for complex output. For simple scripts, the last expression value is auto-returned.

5. Set the resource to require `admin` role

### 4. Add to Claude Code

Add to your Claude Code MCP config (`~/.claude/settings.json` or project settings):

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "node",
      "args": ["/absolute/path/to/servicenow-mcp-server/dist/index.js"],
      "env": {
        "SN_INSTANCE": "your-instance-name",
        "SN_USERNAME": "admin",
        "SN_PASSWORD": "your-password"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|------|-------------|
| `table_read` | Query any ServiceNow table with filtering and pagination |
| `table_create` | Insert a record into any table |
| `table_update` | Update a record (tracks before/after state) |
| `table_delete` | Delete a record |
| `get_table_schema` | Get field definitions for a table |
| `get_choices` | Get choice list values for a field |
| `get_instance_info` | Get instance version and active plugins |
| `run_script` | Execute server-side GlideScript |
| `get_sys_properties` | Read system properties |
| `set_sys_property` | Set a system property value |
| `flow_designer_get` | Fetch a flow's editable processflow JSON |
| `flow_designer_save` | Build/save a flow (PUT the raw processflow object) |
| `flow_designer_compile` | Compile + publish a flow — hands-off "Activate" via `/snapshot` |

> Plus more tool groups not listed above: catalog, change, CMDB, knowledge, import-set, batch, aggregate, and attachments. See `src/index.ts` for the full registration.