ServiceNow Model Context Protocol (MCP) Server

To prevent overwhelming a language model with too many tools, you can load specific subsets of tools called "packages" using the MCP_TOOL_PACKAGE environment variable.

Configuration

• Set a package: export MCP_TOOL_PACKAGE=package_name
• Load all tools (default): Do not set MCP_TOOL_PACKAGE or set it to full.
• Load no tools: Set MCP_TOOL_PACKAGE=none (only list_tool_packages will be available).
• Invalid package: If an invalid name is provided, the none package is loaded and a warning is logged.

Package definitions are managed in config/tool_packages.yaml.

Available Default Packages

• service_desk: Incident handling and user/knowledge lookup.
• catalog_builder: Service catalog management (items, categories, variables, scripting).
• change_coordinator: Change request lifecycle management.
• knowledge_author: Knowledge base and article management.
• platform_developer: Server-side scripting (Script Includes) and workflow development.
• system_administrator: User/group management and system logs.
• agile_management: User stories, epics, and scrum tasks.
• full: All tools.
• none: No tools (except list_tool_packages).

Introspection

Use the list_tool_packages tool to see available package names and identify which package is currently loaded. This tool is available in all packages except none.

To add a new capability to the ServiceNow MCP server, follow a multi-step process involving creating a tool module, exposing it via the package initialization, registering it with the MCP server, and adding tests and documentation. This ensures the new tool is correctly integrated into the Model Completion Protocol (MCP) and accessible to Claude.

Implementation Workflow

1. Create Tool Module: Define the logic in src/servicenow_mcp/tools/.
2. Expose Tool: Update src/servicenow_mcp/tools/__init__.py to include the new tool in __all__.
3. Register Tool: Update server.py to register the tool using the @self.mcp_server.tool() decorator.
4. Test: Add unit tests in the tests/ directory using mocks for API calls.
5. Document: Update docs/ and README.md to describe the tool's parameters and usage.

# 1. Tool Module Implementation (src/servicenow_mcp/tools/)
class {ToolName}Params(BaseModel):
    param1: str = Field(..., description="Description")

class {ToolName}Response(BaseModel):
    success: bool
    message: str

def {tool_name}(config: ServerConfig, auth_manager: AuthManager, params: {ToolName}Params) -> {ToolName}Response:
    # Implementation logic using requests and auth_manager.get_headers()
    ...

# 2. Update tools/__init__.py
from servicenow_mcp.tools.{tool_module} import {tool_name}
__all__ = [..., "{tool_name}"]

# 3. Update server.py
@self.mcp_server.tool()
def {tool_name}(params: {ToolName}Params) -> Dict[str, Any]:
    return {tool_name}_tool(self.config, self.auth_manager, params)

To enable change management capabilities in Claude Desktop, add the ServiceNow MCP server to your claude_desktop_config.json file.

Paths:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: Use the appropriate path for your OS.

Required Environment Variables:

• SERVICENOW_INSTANCE_URL: Your ServiceNow instance URL.
• SERVICENOW_USERNAME: Your ServiceNow username.
• SERVICENOW_PASSWORD: Your ServiceNow password.
• SERVICENOW_AUTH_TYPE: Set to basic for standard authentication.

{
  "mcpServers": {
    "ServiceNow": {
      "command": "/Users/yourusername/dev/servicenow-mcp/.venv/bin/python",
      "args": [
        "-m",
        "servicenow_mcp.cli"
      ],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password",
        "SERVICENOW_AUTH_TYPE": "basic"
      }
    }
  }
}

To simulate an approval hierarchy, follow this pattern:

1. Create a Department Head: Assign administrative or ITIL roles.
2. Create Staff: Set the Department Head's user_id as the manager for the staff user.
3. Create an Assignment Group: Create a group and add members to handle fulfillment tasks.

# 1. Create department head user
bob_result = create_user({
    "user_name": "bob.chiefradiology",
    "first_name": "Bob",
    "last_name": "ChiefRadiology",
    "email": "bob@example.com",
    "title": "Chief of Radiology",
    "department": "Radiology",
    "roles": ["itil", "admin"]
})

# 2. Create staff user with department head as manager
alice_result = create_user({
    "user_name": "alice.radiology",
    "first_name": "Alice",
    "last_name": "Radiology",
    "email": "alice@example.com",
    "title": "Doctor",
    "department": "Radiology",
    "manager": bob_result.user_id
})

# 3. Create assignment group for fulfillment
group_result = create_group({
    "name": "Biomedical Engineering",
    "description": "Group for biomedical engineering staff",
    "members": ["admin"]
})