servicenow-mcp-server
Advanced tools
Multi-instance ServiceNow MCP server with 40+ tools, natural language search, and local script development
Multi-Instance Intelligent Architecture
A revolutionary metadata-driven ServiceNow MCP server that supports multiple ServiceNow instances simultaneously with automatic schema discovery and optimized tool generation.
Part of the Happy Technologies composable service ecosystem
November 2025 Release
October 2025 Release (v2.1)
Note: Version 2.1 includes new local development features. See CLAUDE.md for complete workflow documentation.
Clone and install:
git clone <repository-url>
cd mcp-servicenow-nodejs
npm install
Configure your ServiceNow instance(s):
Option A: Multi-Instance Setup (Recommended)
# Create config file
cp config/servicenow-instances.json.example config/servicenow-instances.json
# Edit with your instances
nano config/servicenow-instances.json
Example multi-instance config:
{
"instances": [
{
"name": "dev",
"url": "https://dev123456.service-now.com",
"username": "admin",
"password": "your-password",
"default": true
},
{
"name": "prod",
"url": "https://prod789012.service-now.com",
"username": "integration_user",
"password": "your-password"
}
]
}
Option B: Single Instance Setup (Legacy)
# Copy environment template
cp .env.example .env
# Edit with your credentials
nano .env
Start the server:
npm run dev
Verify connection:
# Health check
curl http://localhost:3000/health
# List instances
curl http://localhost:3000/instances
Connect your AI assistant:
http://localhost:3000/mcpnpm run stdio (for Claude Desktop)npm run inspectorAll tools automatically support multi-instance operations:
# Default instance (marked with "default": true in config)
SN-List-Incidents { "limit": 10 }
# Specific instance
SN-List-Incidents { "instance": "prod", "limit": 10 }
# List all configured instances
curl http://localhost:3000/instances
Without Instance Parameter:
SN-Create-Incident → creates in default instanceWith Instance Parameter:
SN-Create-Incident { "instance": "prod", ... } → creates in prod instanceGeneric tools work on any ServiceNow table through dynamic schema discovery
| Tool Category | Tools | What They Do |
|---|---|---|
| Generic CRUD | 7 tools | Query, Create, Get, Update on any table |
| Specialized ITSM | 8 tools | Incident, Change, Problem convenience wrappers |
| Convenience Tools | 10 tools | Add-Comment, Add-Work-Notes, Assign, Resolve, Close operations |
| Natural Language | 1 tool | Query using plain English instead of encoded queries |
| Update Set Management | 6 tools | Set, list, move, clone, inspect update sets |
| Background Scripts | 2 tools | Execute scripts, create fix scripts |
| Script Synchronization | 3 tools | Sync scripts with local files, watch mode, Git integration |
| Workflows | 4 tools | Create workflows, activities, transitions |
| Batch Operations | 2 tools | Batch create/update across tables |
| Schema Discovery | 3 tools | Get table schemas, field info, relationships |
| Multi-Instance | 2 tools | Switch instances, get current instance |
| MCP Resources | 8 resources | Read-only URIs for table lists, common tables, field info |
| Category | Example Tables |
|---|---|
| 🏆 Core ITSM | incident, change_request, problem, sc_request, sc_req_item |
| 📦 Service Catalog | sc_cat_item, catalog_ui_policy, item_option_new |
| 👥 User Management | sys_user, sys_user_group, sys_user_role |
| 🔧 CMDB & Assets | cmdb_ci, alm_asset, cmdb_rel_ci |
| ⚙️ Platform Development | sys_script, sys_ui_policy, sys_update_set, sys_update_xml |
| 🔄 Flow Designer | sys_hub_flow, sys_hub_flow_logic, sys_hub_flow_variable |
| 🌊 Workflows | wf_workflow, wf_activity, wf_transition |
| 🔗 Integration | sys_rest_message, sys_ws_definition, sys_import_set |
Standard CRUD Operations (Every Table):
// List records with filtering
SN-List-Incidents({ "query": "state=1^priority=1", "limit": 10 })
// Create new record
SN-Create-Incident({ "short_description": "Email down", "urgency": 1 })
// Get single record
SN-Get-Incident({ "sys_id": "abc123..." })
// Update record
SN-Update-Record({ "table_name": "incident", "sys_id": "abc123...", "data": {...} })
// Query with complex filters
SN-Query-Table({ "table_name": "incident", "query": "active=true", "fields": "number,short_description" })
Specialized Tools:
// Background script execution (automated via sys_trigger)
SN-Execute-Background-Script({ "script": "gs.info('Hello');" })
// Update set management
SN-Get-Current-Update-Set()
SN-Set-Update-Set({ "update_set_sys_id": "abc123..." })
SN-Move-Records-To-Update-Set({ "update_set_id": "xyz789...", "source_update_set": "Default" })
// Table schema introspection
SN-Get-Table-Schema({ "table_name": "incident" })
SN-Discover-Table-Schema({ "table_name": "sys_hub_flow", "include_relationships": true })
// Batch operations
SN-Batch-Create({ "operations": [...] })
SN-Batch-Update({ "updates": [...] })
// Workflow creation
SN-Create-Workflow({ "name": "Auto-Approve", "table": "change_request", "activities": [...] })
Develop ServiceNow scripts locally with Git integration and automatic synchronization:
// Sync local script to ServiceNow
SN-Sync-Script-From-Local({
"local_path": "./scripts/my_business_rule.js",
"table": "sys_script",
"sys_id": "abc123...",
"instance": "dev"
})
// Watch directory for changes (continuous development)
SN-Watch-Scripts({
"directory": "./scripts",
"instance": "dev",
"auto_sync": true
})
// Sync entire directory
SN-Sync-Scripts-Directory({
"directory": "./scripts",
"instance": "dev",
"dry_run": false
})
Benefits:
See CLAUDE.md for complete local development workflow.
Query ServiceNow using plain English instead of encoded queries:
// Natural language queries
SN-Natural-Language-Search({
"table": "incident",
"nl_query": "all high priority incidents assigned to me",
"instance": "dev"
})
SN-Natural-Language-Search({
"table": "change_request",
"nl_query": "emergency changes created this week",
"instance": "prod"
})
SN-Natural-Language-Search({
"table": "problem",
"nl_query": "unresolved problems from network team",
"instance": "dev"
})
Supported Patterns (15+):
When to Use:
Specialized operations for common ITSM tasks:
// Add comments (visible to users)
SN-Incident-Add-Comment({
"sys_id": "abc123...",
"comment": "Issue resolved, monitoring for 24 hours",
"instance": "dev"
})
// Add work notes (internal)
SN-Incident-Add-Work-Notes({
"sys_id": "abc123...",
"work_notes": "Restarted application server, logs attached",
"instance": "dev"
})
// Assign incident
SN-Incident-Assign({
"sys_id": "abc123...",
"assigned_to": "user_sys_id",
"assignment_group": "group_sys_id",
"instance": "dev"
})
// Resolve incident
SN-Incident-Resolve({
"sys_id": "abc123...",
"resolution_code": "Solved (Permanently)",
"resolution_notes": "Fixed configuration error",
"instance": "dev"
})
// Close incident
SN-Incident-Close({
"sys_id": "abc123...",
"close_code": "Solved (Permanently)",
"close_notes": "User confirmed resolution",
"instance": "dev"
})
Available for: Incidents, Change Requests, Problems
Operations: Add-Comment, Add-Work-Notes, Assign, Resolve, Close
Core Service Management:
incident • change_request • change_task • problem • problem_task • sc_request • sc_req_item • sysapproval_approver
Service Catalog:
sc_cat_item • sc_category • item_option_new • catalog_ui_policy • catalog_ui_policy_action
CMDB & Assets:
cmdb_ci • cmdb_ci_* (all CI types) • cmdb_rel_ci • alm_asset • ast_contract
Platform Development:
sys_script • sys_script_client • sys_script_include • sys_ui_script • sys_ui_policy • sys_update_set • sys_update_xml
Flow Designer (NEW!):
sys_hub_flow • sys_hub_flow_base • sys_hub_flow_logic • sys_hub_flow_variable • sys_hub_flow_stage
Workflows:
wf_workflow • wf_activity • wf_transition • wf_version
Integration & APIs:
sys_rest_message • sys_ws_definition • sys_import_set • sys_transform_map
160+ total tables including UI/UX development, user management, knowledge bases, and more!
Start the MCP server:
npm run dev
Launch MCP Inspector in a new terminal:
npm run inspector
Configure connection:
http://localhost:3000/mcpTest tools:
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"servicenow-nodejs": {
"command": "node",
"args": ["/Users/YOUR_USERNAME/WebstormProjects/mcp-servicenow-nodejs/src/stdio-server.js"],
"cwd": "/Users/YOUR_USERNAME/WebstormProjects/mcp-servicenow-nodejs",
"env": {
"SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
"SERVICENOW_USERNAME": "your-username",
"SERVICENOW_PASSWORD": "your-password",
"SERVICENOW_AUTH_TYPE": "basic"
}
}
}
}
Important: Replace YOUR_USERNAME with your actual username and update credentials.
Then restart Claude Desktop (⌘Q and reopen) to see ServiceNow tools appear.
Detailed setup guide: docs/CLAUDE_DESKTOP_SETUP.md
src/
├── server.js # Express HTTP server with SSE transport
├── stdio-server.js # Stdio transport for Claude Desktop
├── mcp-server-consolidated.js # MCP tool registration & routing
├── servicenow-client.js # ServiceNow REST API client
└── config-manager.js # Multi-instance configuration manager
config/
└── servicenow-instances.json # Multi-instance configuration
docs/
├── FLOW_DESIGNER_MCP_FEASIBILITY.md # Flow Designer feasibility analysis
└── MCP_Tool_Limitations.md # API limitation documentation
Key Features:
.env for single-instance backward compatibilityinstance parameterconfig/servicenow-instances.json.env for single-instance backward compatibilitysys_trigger table (runs in ~1 second)docs/FLOW_DESIGNER_MCP_FEASIBILITY.md for detailsSee docs/MCP_Tool_Limitations.md for comprehensive documentation. Key limitations:
Cannot Be Done via REST API:
Workarounds Available:
sys_trigger# Test ServiceNow connectivity
curl -u username:password https://your-instance.service-now.com/api/now/table/incident?sysparm_limit=1
# Check server health
curl http://localhost:3000/health
# List configured instances
curl http://localhost:3000/instances
Multi-instance not working:
config/servicenow-instances.json exists and is valid JSON"default": trueTools not appearing:
Authentication failures:
# Enable verbose logging
DEBUG=true npm run dev
# Check background script execution logs
# ServiceNow: System Logs → System Log → All
# Filter by source: "Script execution"
This project was inspired by and built upon ideas from the Echelon AI Labs ServiceNow MCP Server. We're grateful for their pioneering work in bringing Model Context Protocol capabilities to ServiceNow, which provided valuable insights and inspiration for developing this multi-instance, metadata-driven implementation.
Key innovations we've added:
We encourage the community to explore both implementations and contribute to advancing ServiceNow automation through MCP.
This project is licensed under the MIT License - see the LICENSE file for details.
Copyright © 2025 Happy Technologies LLC
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.
FAQs
Multi-instance ServiceNow MCP server with 40+ tools, natural language search, and local script development
We found that servicenow-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
The campaign amassed more than 75,000 installs by targeting Russian-speaking users seeking access to blocked services.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.