servicenow-mcp 1.1.0

package/.env.example

@@ -0,0 +1,16 @@
+# ServiceNow MCP Configuration
+# Choose ONE authentication method:
+
+# Option 1: Browser SSO (recommended for enterprise)
+# Just set instance URL, then use auth_browser tool
+SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com
+
+# Option 2: Basic Auth (username/password)
+# SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com
+# SERVICENOW_USERNAME=your-username
+# SERVICENOW_PASSWORD=your-password
+
+# Option 3: Session Token Auth (for GraphQL)
+# SERVICENOW_INSTANCE_URL=https://yourinstance.service-now.com
+# SERVICENOW_SESSION_TOKEN=your-cookie-string
+# SERVICENOW_USER_TOKEN=your-g_ck-token

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timothy Schwarz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# ServiceNow MCP Server
+
+[![npm version](https://img.shields.io/npm/v/servicenow-mcp.svg)](https://www.npmjs.com/package/servicenow-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-1.0-green.svg)](https://modelcontextprotocol.io)
+
+A comprehensive Model Context Protocol (MCP) server for ServiceNow ITSM with **browser-based SSO authentication** support.
+
+> **Perfect for enterprise environments** - No API keys required. Works with Okta, Azure AD, and any SSO provider.
+
+## Features
+
+- **Browser Authentication**: Log in via your enterprise SSO (Okta, Azure AD, etc.) - no API keys needed
+- **70+ Tools**: Incidents, Changes, Problems, Catalog, CMDB, Knowledge Base, Users, Approvals, and more
+- **GraphQL & REST Support**: Works with both ServiceNow APIs
+- **Session Management**: Automatic cookie handling and refresh
+
+## Installation
+
+### NPM
+
+```bash
+npm install servicenow-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g servicenow-mcp
+```
+
+### From Source
+
+```bash
+git clone https://github.com/schwarztim/servicenow-mcp.git
+cd servicenow-mcp
+npm install
+npm run build
+```
+
+## Authentication Methods
+
+### 1. Browser SSO (Recommended for Enterprise)
+
+Use the `auth_browser` tool from Claude:
+
+```
+> Use auth_browser to log into ServiceNow
+
+A browser will open. Log in with your SSO credentials.
+Cookies are automatically captured and saved.
+```
+
+Or from command line:
+
+```bash
+npm run auth https://yourinstance.service-now.com
+```
+
+### 2. Basic Auth (Username/Password)
+
+Set environment variables:
+
+```bash
+export SERVICENOW_INSTANCE_URL="https://yourinstance.service-now.com"
+export SERVICENOW_USERNAME="your-username"
+export SERVICENOW_PASSWORD="your-password"
+```
+
+### 3. Session Token Auth
+
+For GraphQL API access:
+
+```bash
+export SERVICENOW_INSTANCE_URL="https://yourinstance.service-now.com"
+export SERVICENOW_SESSION_TOKEN="your-session-cookie"
+export SERVICENOW_USER_TOKEN="your-g_ck-token"
+```
+
+## Usage with Claude
+
+After browser authentication:
+
+```
+> List open P1 incidents
+> Show me change CHG0012345
+> Create an incident for "Email server down"
+> Search CMDB for servers in the Atlanta datacenter
+```
+
+## Available Tools
+
+### Incidents
+
+- `incidents_list` - List incidents with filtering
+- `incidents_get` - Get incident details
+- `incidents_create` - Create new incident
+- `incidents_update` - Update incident
+- `incidents_resolve` - Resolve incident
+
+### Changes
+
+- `changes_list` - List change requests
+- `changes_get` - Get change details
+- `changes_create` - Create change request
+- `changes_tasks` - Get change tasks
+
+### Service Catalog
+
+- `catalog_items` - Browse catalog items
+- `catalog_item_get` - Get item details
+- `catalog_order` - Order catalog item
+- `catalog_requests` - List requests
+
+### CMDB
+
+- `cmdb_list` - Query configuration items
+- `cmdb_get` - Get CI details
+- `cmdb_relationships` - View CI relationships
+- `cmdb_create` - Create CI
+
+### Knowledge Base
+
+- `kb_search` - Search knowledge articles
+- `kb_article_get` - Get article content
+
+### Users & Groups
+
+- `users_search` - Search users
+- `user_get` - Get user details
+- `groups_list` - List groups
+- `group_members` - Get group members
+
+### And many more...
+
+- Approvals, SLAs, Workflows, Email, Events, Audit, Update Sets, Security ACLs, Discovery, etc.
+
+## Configuration
+
+Add to `~/.claude/user-mcps.json`:
+
+```json
+{
+  "mcpServers": {
+    "servicenow": {
+      "command": "node",
+      "args": [
+        "/Users/yourname/Scripts/mcp-servers/servicenow-mcp/dist/index.js"
+      ],
+      "env": {
+        "SERVICENOW_INSTANCE_URL": "https://yourinstance.service-now.com"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### "No authentication configured"
+
+Run `auth_browser` tool or set environment variables.
+
+### "Cookies expired"
+
+Browser cookies are valid for ~8 hours. Re-run `auth_browser` to refresh.
+
+### "Access denied"
+
+Ensure your ServiceNow user has appropriate roles (itil, admin, etc.).
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/schwarztim/servicenow-mcp/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/schwarztim/servicenow-mcp/discussions)
+
+## Acknowledgments
+
+- Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
+- Browser automation powered by [Playwright](https://playwright.dev/)
+
+## License
+
+MIT © Timothy Schwarz - see [LICENSE](LICENSE) for details

package/dist/auth-browser.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * ServiceNow Browser Authentication
+ *
+ * Launches a browser for SSO login and captures session cookies.
+ * Cookies are saved to ~/.servicenow-mcp/cookies.json for MCP to use.
+ */
+import { type Cookie } from "playwright";
+export interface AuthResult {
+    success: boolean;
+    instanceUrl: string;
+    cookies: Cookie[];
+    userToken?: string;
+    error?: string;
+}
+export declare function authenticateViaBrowser(instanceUrl: string): Promise<AuthResult>;
+export declare function loadCookies(): {
+    cookies: string;
+    userToken: string;
+    instanceUrl: string;
+} | null;

package/dist/auth-browser.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * ServiceNow Browser Authentication
+ *
+ * Launches a browser for SSO login and captures session cookies.
+ * Cookies are saved to ~/.servicenow-mcp/cookies.json for MCP to use.
+ */
+import { chromium } from "playwright";
+import { writeFileSync, mkdirSync, existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const COOKIE_DIR = join(homedir(), ".servicenow-mcp");
+const COOKIE_FILE = join(COOKIE_DIR, "cookies.json");
+export async function authenticateViaBrowser(instanceUrl) {
+    console.log(`\n🔐 ServiceNow Browser Authentication`);
+    console.log(`   Instance: ${instanceUrl}`);
+    console.log(`   A browser window will open. Please log in using your SSO credentials.\n`);
+    const browser = await chromium.launch({
+        headless: false, // User needs to see and interact
+        args: ["--disable-blink-features=AutomationControlled"],
+    });
+    const context = await browser.newContext({
+        viewport: { width: 1280, height: 800 },
+        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    });
+    const page = await context.newPage();
+    try {
+        // Navigate to ServiceNow
+        await page.goto(instanceUrl, { waitUntil: "networkidle" });
+        console.log("⏳ Waiting for you to complete SSO login...");
+        console.log("   (The browser will close automatically once authenticated)\n");
+        // Wait for successful authentication by detecting:
+        // 1. URL no longer contains login/saml/sso keywords
+        // 2. We're on a ServiceNow page (contains nav or workspace)
+        let authenticated = false;
+        let attempts = 0;
+        const maxAttempts = 300; // 5 minutes - allows time for MFA flows
+        while (!authenticated && attempts < maxAttempts) {
+            await page.waitForTimeout(1000);
+            const currentUrl = page.url();
+            // Check if we're past the login page
+            const isLoginPage = currentUrl.includes("/login") ||
+                currentUrl.includes("/saml") ||
+                currentUrl.includes("/sso") ||
+                currentUrl.includes("idp") ||
+                currentUrl.includes("okta") ||
+                currentUrl.includes("auth0") ||
+                currentUrl.includes("login.microsoftonline");
+            const isServiceNowPage = currentUrl.includes("service-now.com") &&
+                (currentUrl.includes("/nav/") ||
+                    currentUrl.includes("/now/") ||
+                    currentUrl.includes("/$") ||
+                    currentUrl.includes("/welcome"));
+            if (!isLoginPage && isServiceNowPage) {
+                authenticated = true;
+                console.log("✅ Authentication detected!");
+            }
+            attempts++;
+        }
+        if (!authenticated) {
+            throw new Error("Authentication timeout. Please try again.");
+        }
+        // Get all cookies from the session
+        const cookies = await context.cookies();
+        // Try to extract user token from page (used for CSRF protection)
+        let userToken;
+        try {
+            userToken = await page.evaluate(() => {
+                // ServiceNow stores g_ck (security token) in window object
+                return window.g_ck || window.NOW?.g_ck || "";
+            });
+        }
+        catch {
+            // Token extraction optional
+        }
+        // Save cookies to file
+        ensureCookieDir();
+        const cookieData = {
+            instanceUrl: instanceUrl.replace(/\/$/, ""),
+            cookies: cookies,
+            userToken: userToken,
+            timestamp: new Date().toISOString(),
+        };
+        writeFileSync(COOKIE_FILE, JSON.stringify(cookieData, null, 2));
+        console.log(`\n✅ Authentication successful!`);
+        console.log(`   Cookies saved to: ${COOKIE_FILE}`);
+        console.log(`   Found ${cookies.length} cookies`);
+        if (userToken) {
+            console.log(`   User token captured`);
+        }
+        await browser.close();
+        return {
+            success: true,
+            instanceUrl: instanceUrl.replace(/\/$/, ""),
+            cookies,
+            userToken,
+        };
+    }
+    catch (error) {
+        await browser.close();
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`\n❌ Authentication failed: ${message}`);
+        return {
+            success: false,
+            instanceUrl,
+            cookies: [],
+            error: message,
+        };
+    }
+}
+function ensureCookieDir() {
+    if (!existsSync(COOKIE_DIR)) {
+        mkdirSync(COOKIE_DIR, { recursive: true });
+    }
+}
+export function loadCookies() {
+    try {
+        if (!existsSync(COOKIE_FILE)) {
+            return null;
+        }
+        const data = JSON.parse(readFileSync(COOKIE_FILE, "utf-8"));
+        // Check if cookies are expired (older than 45 minutes)
+        // ServiceNow sessions typically expire in ~1 hour, so we check earlier
+        const timestamp = new Date(data.timestamp);
+        const ageMinutes = (Date.now() - timestamp.getTime()) / (1000 * 60);
+        if (ageMinutes > 45) {
+            console.error("⚠️  Cookies are older than 45 minutes (ServiceNow sessions expire in ~1 hour). Please re-authenticate with auth_browser tool.");
+            return null;
+        }
+        // Format cookies as header string
+        const cookieString = data.cookies
+            .map((c) => `${c.name}=${c.value}`)
+            .join("; ");
+        return {
+            cookies: cookieString,
+            userToken: data.userToken || "",
+            instanceUrl: data.instanceUrl,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// CLI entry point
+if (process.argv[1]?.endsWith("auth-browser.ts") ||
+    process.argv[1]?.endsWith("auth-browser.js")) {
+    const instanceUrl = process.argv[2] || process.env.SERVICENOW_INSTANCE_URL;
+    if (!instanceUrl) {
+        console.error("Usage: npm run auth <SERVICENOW_INSTANCE_URL>");
+        console.error("   Or: set SERVICENOW_INSTANCE_URL environment variable");
+        process.exit(1);
+    }
+    authenticateViaBrowser(instanceUrl)
+        .then((result) => {
+        process.exit(result.success ? 0 : 1);
+    })
+        .catch((error) => {
+        console.error("Fatal error:", error);
+        process.exit(1);
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * ServiceNow MCP Server
+ *
+ * Comprehensive MCP for ServiceNow ITSM operations:
+ * - Incidents, Changes, Problems
+ * - Service Catalog & Requests
+ * - CMDB Configuration Items
+ * - Knowledge Base
+ * - Users, Groups, Approvals
+ *
+ * Supports:
+ * - Browser-based SSO authentication (recommended for enterprise)
+ * - REST Table API (basic auth)
+ * - GraphQL API (session-based)
+ */
+export {};