ServiceNow Script Manager

This repository contains two moving pieces that work together through the Model‑Context Protocol (MCP):

1. sn_mcp_tools.py – a FastMCP server exposing CRUD tools for ServiceNow Business Rules, Client Scripts, and Script Includes.
2. script_generator.py – a Gradio UI that talks to the MCP server to generate, edit, and deploy scripts with GPT‑4o.

---

Setup Guide

Follow these simple steps to get the solution up and running:

1. Clone the Repository

git clone https://github.com/yvain13/ServiceNow-Scripts-MCP.git
cd ServiceNow-Scripts-MCP

2. Set Up Python Environment

# Create virtual environment
python -m venv venv

# Activate on macOS/Linux
source venv/bin/activate

# Activate on Windows
# venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Configure Environment Variables

Create a file named .env in the root directory with your credentials:

# OpenAI API Key
OPENAI_API_KEY=sk-your-api-key-here

# ServiceNow Instance Details
SERVICENOW_URL=https://your-instance.service-now.com/
SERVICENOW_USER=your-username
SERVICENOW_PASS=your-password
SERVICENOW_AUTH_TYPE=basic

4. Start the Application

Run these commands in separate terminal windows:

# Terminal 1: Start the FastMCP server
python sn_mcp_tools.py

# Terminal 2: Start the Gradio UI
python script_generator.py

Open the URL shown in the second terminal (typically http://127.0.0.1:7860) in your web browser.

---

How it works (architecture)

┌───────────────┐       HTTP/MCP        ┌────────────────────────┐
│ Gradio UI     │  ───────────────────▶ │ FastMCP Server         │
│ (script_…py)  │ ◀───────────────────  │ (sn_mcp_tools.py)      │
└───────────────┘       MCP calls       └──────────┬─────────────┘
       ▲  GPT‑4o                                    │ REST API
       │                                            ▼
       └─ openai                                    ServiceNow Table API

1. User enters an instruction or selects an existing script.
2. Gradio UI (client) calls GPT‑4o or an MCP tool.
3. FastMCP server translates the tool call into a ServiceNow REST request.
4. Results stream back to the UI via HTTP.

---

Key Files

File	Purpose	Run with
sn_mcp_tools.py	Exposes ServiceNow CRUD operations for scripts via MCP	python sn_mcp_tools.py
script_generator.py	Gradio UI for script management	python script_generator.py
mcp_client.py	Example showing how to create an MCPAgent	python mcp_client.py
requirements.txt	Python dependencies	pip install -r requirements.txt

---

Example MCP Client Usage

The mcp_client.py file provides a simple example of how to create an MCPAgent that can communicate with your FastMCP server. This is especially useful for developers who want to build their own applications that leverage the ServiceNow tools without using the Gradio UI.

# Example usage from mcp_client.py
from mcp_use import MCPAgent, MCPClient
from langchain_openai import ChatOpenAI

# Create a client that connects to the FastMCP server
config = {
    "mcpServers": {
        "http": {
            "url": "http://localhost:9123/mcp"
        }
    }
}
client = MCPClient.from_dict(config)

# Create the LLM
llm = ChatOpenAI(model="gpt-4o")

# Create the agent
agent = MCPAgent(llm=llm, client=client, max_steps=30)

# Run a query that will use the MCP tools
result = agent.run("Create a business rule for the incident table that logs when a VIP incident is created")
print(result)

You can use this pattern to integrate ServiceNow tool access in any Python application or script.

---

Connect from Claude, Windsurf, or Cursor

If you're using an MCP‑aware client (Anthropic Claude, Windsurf browser extension, Cursor editor, etc.) just point it to your local FastMCP server—no extra proxy needed.

Add this to your client‑side mcp.config.json (or equivalent):

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:9123/mcp"
      ]
    }
  }
}

That's it—once the FastMCP server is running on port 9123, your editor or chat client can call the available tools exactly the same way the Gradio UI does.

Available MCP Tools

The FastMCP server provides comprehensive CRUD operations for ServiceNow scripts:

Business Rules

• create_business_rule(name, table, script, when, active, description) - Create a new business rule
• list_business_rules(query, table, limit) - List business rules with filtering
• update_business_rule(sys_id, script, name, table, when, active, description) - Update existing business rule
• get_business_rule(sys_id) - Get specific business rule by sys_id

Client Scripts

• create_client_script(name, table, script, type, active, description) - Create a new client script
• list_client_scripts(query, table, limit) - List client scripts with filtering
• update_client_script(sys_id, script, name, table, type, active, description) - Update existing client script
• get_client_script(sys_id) - Get specific client script by sys_id

Script Includes

• create_script_include(name, script, active, description) - Create a new script include
• update_script_include(sys_id, script, name, active, description) - Update existing script include
• get_script_include(sys_id) - Get specific script include by sys_id

All tools include proper error handling, authentication, and detailed logging for debugging.

---

Troubleshooting

• 401/403 from ServiceNow – check username/password and that the user has rest_api_explorer or admin role.
• "Event loop is closed" – make sure you're using the provided script_generator.py (it runs on a shared asyncio loop).
• Nothing happens after clicking buttons – confirm the FastMCP server is running on localhost:9123 (default) and reachable.

---

License

MIT 2025 Tushar Mishra