Personal MCP Servicenow
Started as personal project but evolved into something used widely at my workplace and beyond. MCP server for ServiceNow
Installation
npx personal-mcp-servicenowAsk AI about Personal MCP Servicenow
Powered by Claude Β· Grounded in docs
I know everything about Personal MCP Servicenow. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π Personal MCP ServiceNow Integration
A Model Context Protocol (MCP) server for ServiceNow integration, featuring AI-powered natural language processing, consolidated architecture, and enterprise-grade security across multiple ServiceNow tables with zero functional regression.
π Support This Project
If this ServiceNow MCP integration is valuable to your workflow, consider supporting its continued development:
Your support helps maintain and improve this project with new features, bug fixes, and better documentation.
Installation
Option 1: Binary (Recommended)
Download the latest binary for your platform from Releases:
| Platform | Download |
|---|---|
| macOS (Apple Silicon) | mcp-servicenow-darwin-arm64 |
| macOS (Intel) | mcp-servicenow-darwin-x86_64 |
| Linux | mcp-servicenow-linux-amd64 |
| Windows | mcp-servicenow-windows-amd64.exe |
macOS/Linux Setup:
# Download and install
chmod +x mcp-servicenow-darwin-arm64
sudo mv mcp-servicenow-darwin-arm64 /usr/local/bin/mcp-servicenow
# Run setup wizard
mcp-servicenow --setup
# Verify
mcp-servicenow --version
Windows Setup:
# Move to a directory in your PATH
Move-Item mcp-servicenow-windows-amd64.exe C:\Users\$env:USERNAME\AppData\Local\bin\mcp-servicenow.exe
# Run setup wizard
mcp-servicenow.exe --setup
Claude Code Configuration
Add to your Claude Code MCP configuration (~/.claude/claude_desktop_config.json):
{
"mcpServers": {
"servicenow": {
"command": "/usr/local/bin/mcp-servicenow"
}
}
}
Option 2: From Source
git clone <repo-url>
cd mcp-servicenow
pip install -r requirements.txt
python personal_mcp_servicenow_main.py
Option 3: Docker (Cloud / Network Agents)
For hosting the MCP server so that any network-capable agent (N8N, LangChain, custom agents, etc.) can connect to it β not just Claude Code locally.
# Build the image
docker build -t mcp-servicenow .
# Local testing only β load credentials from a gitignored .env file
docker run -d \
-p 8000:8000 \
--env-file .env.local \
--name mcp-servicenow \
mcp-servicenow
β οΈ Do not pass secrets with
-e KEY=valueon the command line. They land in shell history and are visible viaps/docker inspect. For production, see Production: Azure Container Apps + Key Vault.
Agents connect via SSE at: http://<your-host>:8000/sse
See Cloud Hosting for the full setup guide.
π What's New in v3.0
v3.0 is a quality-of-life and performance release with no breaking API changes for end users.
| Change | Impact |
|---|---|
| Tool consolidation | 24 table-specific wrappers replaced by 5 generic tools (search_records, get_record, get_record_summary, find_similar, filter_records) β pass any supported table name as a parameter. Total tools reduced from 55 to 36. |
| Faster API responses | All requests now include sysparm_exclude_reference_link=true and sysparm_no_count=true, reducing payload size and eliminating unnecessary server-side COUNT queries. |
| Deterministic pagination | Paginated queries automatically sort by sys_created_on DESC, preventing records from being skipped or duplicated across pages. |
| Centralized URL encoding | sysparm_query values are percent-encoded in a single place, fixing edge cases where special characters caused silent over-fetching. |
| Correct HTTP semantics | Partial updates to private tasks now use PATCH instead of PUT. |
Upgrading from v2.x requires no configuration changes.
π¨ Version 2.0 - BREAKING CHANGES (from v1.x)
If you're upgrading from v1.x:
- π Read the Migration Guide:
MIGRATION_V2.md- Complete step-by-step migration instructions - π Review Breaking Changes:
CHANGELOG.md- Full list of changes and new features - π§ OAuth 2.0 Required: Basic authentication has been removed - OAuth setup is mandatory
New Installations: Start directly with v3.0 - follow the setup instructions below.
β¨ Features
π§ AI-Powered Natural Language Processing (NEW)
- Conversational Queries - "Show me high priority incidents from last week" automatically converted to ServiceNow syntax
- Confidence Scoring - 0.0-1.0 confidence ratings with intelligence metadata
- Smart Templates - Enterprise-grade pre-built filter patterns for common scenarios
- Query Explanation - Human-readable explanations and SQL equivalents for every query
- Filter Intelligence - Automatic validation, correction, and improvement suggestions
π‘οΈ Enterprise-Grade Security (Enhanced)
- OAuth 2.0 Exclusive - Enhanced security with no basic auth fallback
- ReDoS Protection - Windows-compatible protection against Regular Expression Denial of Service attacks
- Input Validation - Pre-validation of all text inputs to prevent malicious attacks
- Attack Resistance - Comprehensive protection against SQL injection, XSS, and path traversal
- Security Monitoring - Real-time validation with intelligent safety warnings
π¦ Consolidated Architecture (v3.0)
- 55 β 36 tools - 24 near-duplicate wrappers replaced by 5 generic parameterized tools
- Unified Interface -
search_records(table, query)works across all 8 supported tables - Zero Regression - Generic tools delegate to the same core engine and API path
- Performance optimized - All requests include performance params, centralized URL encoding, deterministic pagination
- AI Integration - Natural language processing seamlessly integrated throughout
ποΈ Comprehensive Table Support (Enhanced)
- Incidents - AI-enhanced similarity search, intelligent filtering, and priority queries
- Change Requests - Complete change management with natural language processing
- User Requests - Service catalog handling with smart filter generation
- Knowledge Base - Article search with AI-powered category intelligence
- Private Tasks - Full CRUD operations with intelligent validation
- CMDB Configuration Items - 100+ CI types with AI-enhanced discovery and search
β‘ Performance Revolution (5x Improvement)
- 5x Faster Processing - Compiled regex patterns vs SpaCy NLP (47MB β <1MB)
- Enhanced Field Selection - Smart field optimization (60% data reduction)
- Pagination Support - Complete result retrieval preventing data loss
- OAuth Token Caching - 1-hour token reuse with automatic refresh
- Early Exit Strategy - Return first successful match for efficiency
- Async Architecture - Non-blocking operations with optimized concurrency
π CMDB Discovery & Management (Enhanced)
- AI-Enhanced Discovery - Intelligent CI type detection and categorization
- 100+ CI Type Support - Servers, databases, applications, storage, networking, cloud resources
- Multi-Attribute Search - Natural language queries across name, IP, location, status
- Relationship Analysis - AI-powered similar CI detection and dependency mapping
- Business Service Mapping - Complete infrastructure-to-service relationships with intelligence
ποΈ Code Quality & Architecture Excellence
- SonarCloud Compliance - All cognitive complexity violations resolved (β€15 limit)
- PEP 8 Standards - Complete snake_case naming convention adherence
- Modular Design - Single responsibility principle applied throughout
- Helper Functions - Enhanced maintainability and testability
- Constants Module - Centralized configuration eliminating hardcoded values
- Query Validation - Built-in ServiceNow syntax validation with intelligent corrections
π οΈ Available Tools (36)
π¦ Generic Table Tools (5) β NEW in v3.0
These replace 24 table-specific wrappers. Pass any supported table: incident, change_request, sc_req_item, sc_task, universal_request, kb_knowledge, vtb_task, task_sla.
search_records(table, query)- Text similarity search across any supported tableget_record_summary(table, number)- Short description for a single recordget_record(table, number)- Full detail fields for a single recordfind_similar(table, number)- Find records similar to an existing recordfilter_records(table, filters, fields)- Query with field-value filters, operators, and date ranges
π§ Intelligent Query Tools (5)
intelligent_search(query, table, context)- Natural language search: "high priority incidents from last week"build_smart_servicenow_filter(query, table, context)- Convert natural language to ServiceNow syntaxexplain_servicenow_filters(filters, table)- Human-readable explanations of complex filtersget_servicenow_filter_templates()- Pre-built filters for common scenariosget_query_examples()- Natural language examples that work with intelligent search
π§ Server & Authentication (5)
nowtest()- Server connectivity verificationnow_test_oauth()- OAuth 2.0 authentication testingnow_auth_info()- Current authentication method infonowtestauth()- ServiceNow API endpoint validationnowtest_auth_input(table)- Table description retrieval
π₯ Priority Incidents (1)
get_priority_incidents(priorities, start_date, end_date, additional_filters, include_metadata)- Priority queries with date range filtering and metadata
π Knowledge Base (3)
similar_knowledge_for_text(input_text, kb_base, category)- Article search with optional category/knowledge base filteringget_knowledge_by_category(category, kb_base)- Category-based article retrievalget_active_knowledge_articles(input_text)- Published knowledge articles
π Private Task CRUD (2)
create_private_task(task_data)- Create new private tasks (vtb_task)update_private_task(task_number, update_data)- Update existing tasks via PATCH
β±οΈ SLA Management (10)
similar_slas_for_text(input_text)- SLA search by textget_slas_for_task(task_number)- All SLAs for a specific taskget_sla_details(sla_sys_id)- Detailed SLA informationget_breaching_slas(time_threshold_minutes)- SLAs at risk of breachingget_breached_slas(filters, days)- Already breached SLAsget_slas_by_stage(stage, additional_filters)- SLAs by stageget_active_slas(filters)- Currently active SLAsget_sla_performance_summary(filters, days)- SLA performance metricsget_recent_breached_slas(days)- Recently breached SLAsget_critical_sla_status()- High-priority SLA dashboard
π₯οΈ CMDB Configuration Items (6)
find_cis_by_type(ci_type)- Find CIs by type (100+ types supported)search_cis_by_attributes(name, ip_address, location, status)- Multi-attribute CI searchget_ci_details(ci_number)- Comprehensive CI detailssimilar_cis_for_ci(ci_number)- Find similar configuration itemsget_all_ci_types()- List all available CI typesquick_ci_search(search_term)- Fast CI search by name, IP, or number
Supported CI Types (Auto-Discovered)
Core Infrastructure Cloud & Virtualization Storage & Networking
βββ cmdb_ci_server βββ cmdb_ci_vm_object βββ cmdb_ci_storage_device
βββ cmdb_ci_database βββ cmdb_ci_vpc βββ cmdb_ci_san
βββ cmdb_ci_hardware βββ cmdb_ci_subnet βββ cmdb_ci_ip_network
βββ cmdb_ci_service βββ cmdb_ci_cloud_* βββ cmdb_ci_load_balancer
Applications Facilities Specialized Equipment
βββ cmdb_ci_appl βββ cmdb_ci_datacenter βββ cmdb_ci_ups_*
βββ cmdb_ci_business_* βββ cmdb_ci_rack βββ cmdb_ci_monitoring_*
βββ cmdb_ci_cluster βββ cmdb_ci_computer_room βββ 80+ more types...
π Prerequisites
- Python 3.8+
- ServiceNow Instance (Developer, Enterprise, or higher)
- API Access - REST API enabled with appropriate permissions
- OAuth 2.0 Credentials:
CLIENT_IDandCLIENT_SECRET(contact maintainer)
π Quick Start
1. Installation
git clone https://github.com/Papamzor/personal-mcp-servicenow.git
cd personal-mcp-servicenow
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\\Scripts\\activate
# Install dependencies
pip install -r requirements.txt
2. Configuration
Create .env file in project root:
# OAuth 2.0 Authentication (Required)
SERVICENOW_INSTANCE=https://your-instance.service-now.com
SERVICENOW_CLIENT_ID=your_oauth_client_id
SERVICENOW_CLIENT_SECRET=your_oauth_client_secret
β οΈ OAuth 2.0 Credentials Required: This application exclusively uses OAuth 2.0 authentication for security. Contact the project maintainer to obtain OAuth client credentials for your ServiceNow instance.
3. OAuth 2.0 Setup
See OAUTH_SETUP_GUIDE.md for complete ServiceNow OAuth configuration, or contact the maintainer for pre-configured credentials.
4. Verification
# Test environment setup (local test - no ServiceNow connection needed), expected result 2/3 pass (.env file should not be readable)
python -m Testing.test_oauth_simple
# Test actual ServiceNow connectivity by running some CMDB tools (requires valid .env configuration)
python -m Testing.test_cmdb_tools
# Test OAuth with your ServiceNow instance (requires OAuth setup), should return token validity details
python -c "import asyncio; from utility_tools import now_test_oauth; print(asyncio.run(now_test_oauth()))"
Verification Steps Explained:
- Step 1: Tests OAuth client creation and environment variables (offline test)
- Step 2: Tests actual ServiceNow API connectivity and CMDB functionality
- Step 3: Tests OAuth authentication flow with your ServiceNow instance
5. Claude Desktop Integration
To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop settings:
Location of config file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Add this configuration:
{
"mcpServers": {
"servicenow": {
"command": "python",
"args": ["/full/path/to/personal-mcp-servicenow/tools.py"],
"env": {
"SERVICENOW_INSTANCE": "https://your-instance.service-now.com",
"SERVICENOW_CLIENT_ID": "your_oauth_client_id",
"SERVICENOW_CLIENT_SECRET": "your_oauth_client_secret"
}
}
}
}
Important Notes:
- Replace
/full/path/to/personal-mcp-servicenow/with your actual installation path - Replace the environment variables with your actual ServiceNow credentials
- Restart Claude Desktop after adding this configuration
- The server will auto-start when Claude Desktop launches
Alternative: Using .env file (Recommended)
If you prefer to keep credentials in your .env file:
{
"mcpServers": {
"servicenow": {
"command": "python",
"args": ["/full/path/to/personal-mcp-servicenow/tools.py"]
}
}
}
6. Standalone Server (Optional)
To run the MCP server independently:
python tools.py
7. Cloud Hosting & Network Agents (Docker)
By default the server uses stdio transport, which means it runs as a local subprocess controlled by an MCP client like Claude Code. To make it accessible over the network to any agent, the server must be switched to SSE (Server-Sent Events) transport. The Docker image handles this automatically via the MCP_TRANSPORT environment variable.
Transport modes
MCP_TRANSPORT | How it runs | Use case |
|---|---|---|
stdio (default) | Subprocess, communicates via stdin/stdout | Local Claude Code |
sse | HTTP server, agents connect via SSE | Docker, cloud, N8N, any network agent |
Build and run (local testing)
docker build -t mcp-servicenow .
docker run -d \
-p 8000:8000 \
--env-file .env.local \
--name mcp-servicenow \
mcp-servicenow
Where .env.local contains:
SERVICENOW_INSTANCE=https://your-instance.service-now.com
SERVICENOW_CLIENT_ID=your_oauth_client_id
SERVICENOW_CLIENT_SECRET=your_oauth_client_secret
β οΈ Add
.env.localto.gitignore. Never commit it. The--env-fileform keeps credentials out of shell history andpsoutput, but the file is still plaintext on disk β only use this for local testing.
The image sets MCP_TRANSPORT=sse by default, so no extra flags are needed. Credentials are never baked into the image.
You can also override the host and port:
docker run -d \
-p 9000:9000 \
-e MCP_TRANSPORT=sse \
-e MCP_HOST=0.0.0.0 \
-e MCP_PORT=9000 \
--env-file .env.local \
mcp-servicenow
Production: Azure Container Apps + Key Vault
For production, store the ServiceNow credentials in Azure Key Vault and let Azure Container Apps fetch them at runtime using the Container App's system-assigned managed identity. No secrets ever appear in env vars on your machine, in source control, in shell history, or in docker inspect output on the host.
The flow:
Key Vault (secrets)
β reads via RBAC
Container App (managed identity)
β injects as env vars via secretRef
mcp-servicenow container
1. Push the image to Azure Container Registry
az acr create -g <rg> -n <acrName> --sku Basic
az acr login -n <acrName>
docker tag mcp-servicenow <acrName>.azurecr.io/mcp-servicenow:latest
docker push <acrName>.azurecr.io/mcp-servicenow:latest
2. Create a Key Vault and store the three secrets
az keyvault create -g <rg> -n <kvName> --enable-rbac-authorization true
az keyvault secret set --vault-name <kvName> --name servicenow-instance --value "https://your-instance.service-now.com"
az keyvault secret set --vault-name <kvName> --name servicenow-client-id --value "your_oauth_client_id"
az keyvault secret set --vault-name <kvName> --name servicenow-client-secret --value "your_oauth_client_secret"
3. Create the Container App with a system-assigned managed identity
az containerapp env create -g <rg> -n <envName> --location westeurope
az containerapp create \
-g <rg> -n mcp-servicenow \
--environment <envName> \
--image <acrName>.azurecr.io/mcp-servicenow:latest \
--target-port 8000 --ingress external \
--system-assigned \
--registry-server <acrName>.azurecr.io
4. Grant the Container App's identity read access to the vault
PRINCIPAL_ID=$(az containerapp show -g <rg> -n mcp-servicenow --query identity.principalId -o tsv)
KV_ID=$(az keyvault show -g <rg> -n <kvName> --query id -o tsv)
az role assignment create \
--assignee "$PRINCIPAL_ID" \
--role "Key Vault Secrets User" \
--scope "$KV_ID"
5. Wire Key Vault references into Container App secrets and env vars
az containerapp secret set \
-g <rg> -n mcp-servicenow \
--secrets \
"servicenow-instance=keyvaultref:https://<kvName>.vault.azure.net/secrets/servicenow-instance,identityref:system" \
"servicenow-client-id=keyvaultref:https://<kvName>.vault.azure.net/secrets/servicenow-client-id,identityref:system" \
"servicenow-client-secret=keyvaultref:https://<kvName>.vault.azure.net/secrets/servicenow-client-secret,identityref:system"
az containerapp update \
-g <rg> -n mcp-servicenow \
--set-env-vars \
"SERVICENOW_INSTANCE=secretref:servicenow-instance" \
"SERVICENOW_CLIENT_ID=secretref:servicenow-client-id" \
"SERVICENOW_CLIENT_SECRET=secretref:servicenow-client-secret"
Why this is safer than -e flags
Risk with docker run -e ... | How this approach mitigates it |
|---|---|
| Secrets in shell history | Never typed on the command line |
Visible via ps auxe / docker inspect | Stored encrypted in Key Vault, resolved by the platform |
| Leak into CI logs / screen-shares | Never appear in plaintext anywhere outside the vault |
| Rotation requires rebuild/redeploy | Update the secret in Key Vault; the Container App picks up the new value on next revision |
| Anyone with repo access sees them | Access gated by Azure RBAC + managed identity, not file permissions |
To rotate a credential, update the Key Vault secret and create a new Container App revision (az containerapp update --revision-suffix vN).
Connecting agents
Once running, agents connect to the SSE endpoint:
http://<your-host>:8000/sse
N8N: Use the MCP Client node and point it at the SSE URL above.
LangChain / custom agents: Use any MCP-compatible SSE client library pointed at the same URL.
Claude Code (remote): Add to your MCP config:
{
"mcpServers": {
"servicenow": {
"type": "sse",
"url": "http://<your-host>:8000/sse"
}
}
}
Development dependency separation
When developing locally, install the full dev toolchain:
pip install -r requirements-dev.txt
For production builds (including Docker), only production dependencies are installed:
pip install -r requirements.txt
requirements-dev.txt includes everything in requirements.txt plus pytest, pytest-cov, and coverage. These are never installed in the Docker image.
ποΈ Architecture
MCP Server (FastMCP β 36 tools)
βββ Tool Layer
β βββ Generic Wrappers (generic_tool_wrappers.py β 5 tools for 8 tables)
β βββ Consolidated Tools (consolidated_tools.py β priority, knowledge, SLA)
β βββ Private Task CRUD (vtb_task_tools.py β create, update via PATCH)
β βββ CMDB Tools (cmdb_tools.py β 6 tools, 100+ CI types)
β βββ Intelligent Query Tools (intelligent_query_tools.py β NLP)
βββ Core Engine
β βββ Generic Table Tools (generic_table_tools.py β pagination, sorting, filtering)
β βββ Query Intelligence (query_intelligence.py β regex NLP)
βββ API Layer
β βββ OAuth 2.0 Client (oauth_client.py β token management)
β βββ HTTP Client (service_now_api_oauth.py β perf params, URL encoding)
βββ Utilities
βββ Server Tools (utility_tools.py)
βββ Date Utils (date_utils.py)
βββ Constants & Config (constants.py, config_loader.py)
π§ͺ Testing Infrastructure
The project includes comprehensive testing capabilities:
Test Categories
- OAuth Testing - OAuth 2.0 client creation and environment validation
- CMDB Testing - Configuration Item discovery and ServiceNow connectivity
- Integration Testing - End-to-end OAuth authentication with ServiceNow
Run Tests
# Test environment setup (offline)
python -m Testing.test_oauth_simple
# Test ServiceNow connectivity and CMDB functionality
python -m Testing.test_cmdb_tools
π Performance & Code Quality
- 50-60% Token Usage Reduction - Optimized field selection and query efficiency
- Async Operations - Non-blocking API calls with proper error handling
- Smart Field Selection - Essential vs. detailed modes for optimal performance
- Efficient Error Handling - Graceful degradation and meaningful error messages
- Resource Management - Configurable limits and intelligent caching
- SonarCloud Compliance - Cognitive complexity reduced from 20 to β€8 in critical functions
- PEP 8 Standards - Complete snake_case naming convention compliance
- Modular Architecture - Helper functions improve maintainability and testability
- ServiceNow Query Reliability - Comprehensive pagination and result validation preventing missing critical incidents
- Constants Module - Centralized configuration eliminating hardcoded strings and magic values
- Query Validation Framework - Built-in ServiceNow syntax validation with completeness checks
π§ Advanced Configuration
Field Customization
# Essential fields (fast queries)
ESSENTIAL_FIELDS = ["number", "short_description", "priority", "state"]
# Detailed fields (comprehensive data)
DETAILED_FIELDS = [..., "work_notes", "comments", "assigned_to", "sys_created_on"]
Date Filtering
# Multiple date formats supported
filters = {
"sys_created_on_gte": "2024-01-01", # Standard format
"sys_created_on": ">=javascript:gs.daysAgoStart(14)", # ServiceNow JS
"state": "1", # Active state
"priority": "1" # High priority
}
CMDB Discovery
The system automatically discovers all CMDB tables in your ServiceNow instance and updates the supported CI types list. No manual configuration required!
π€ Contributing
Contributions welcome! Please see Contributing Guidelines.
- Fork the repository
- Create feature branch (
git checkout -b feature/amazing-feature) - Commit changes (
git commit -m 'Add amazing feature') - Push to branch (
git push origin feature/amazing-feature) - Open Pull Request
π Documentation
- OAuth Setup Guide - Complete OAuth 2.0 configuration
- Project Documentation - Comprehensive technical documentation
- ServiceNow Query Guide - Proper ServiceNow syntax and best practices
- Test Documentation - Testing procedures and scenarios
- Optimization Guide - Performance improvements and token usage
- Cloud Hosting - Docker setup and network agent integration
π Security
- OAuth 2.0 Exclusive - No username/password authentication supported
- Zero Password Storage - Enhanced security through OAuth-only approach
- Automatic Token Management - Secure token refresh and expiration handling
- Environment-Based Config - All credentials via environment variables only
- Proper API Scoping - Controlled permissions and access management
- No Credential Exposure - Comprehensive error handling without information disclosure
π Project Statistics
- 36 MCP Tools covering 8 ServiceNow tables + CMDB (100+ CI types)
- 537 tests passing with 80% overall code coverage
- OAuth 2.0 Exclusive - Enhanced security with single authentication method
- SonarCloud Compliant - All cognitive complexity violations resolved (CC β€ 15)
- PEP 8 Compliant - 100% snake_case naming convention adherence
π License
This project is licensed under the MIT License - see the LICENSE file for details.
β Star this project if you find it useful!
π Found a bug? Please open an issue.
π‘ Have a feature request? We'd love to hear from you!
