📋 Table of Contents

• 🌟 Overview
• ✨ Key Features
• 🏗️ Architecture
• ⚡ Quick Start
• 🔧 Installation & Configuration
• 💬 How to Use
• 🎛️ Available Tools
• 🐛 Troubleshooting

🌟 Overview

The ServiceNow MCP Exporter transforms the tedious task of data extraction into a simple conversation. By integrating with an AI chat client like Claude Desktop, this tool allows you to run massive, long-running export jobs in the background without worrying about timeouts or complex scripts.

Just ask for the data you need, and the server handles the rest, saving the completed CSV file directly to your computer.

✨ Key Features

🏗️ Architecture

The tool acts as a smart assistant for your data export tasks. When you ask it to perform an export, it connects to ServiceNow on your behalf, downloads the data in manageable chunks, and assembles it into a single CSV file on your computer.

graph TD
    subgraph "Your Computer"
        A[You via Claude Desktop] -->|1. "Export the incident table"| B(MCP Server);
        B -->|4. Saves File| D[Downloads Folder];
    end
    
    subgraph "The Cloud"
        C[ServiceNow Instance]
    end

    B -->|2. Fetches Data in Batches| C;
    C -->|3. Sends Data Back| B;
    A -->|5. "What's the status?"| B;
    B -->|6. "Almost done!"| A;

⚡ Quick Start

1. Clone the repository and navigate into the directory.
2. Run uv venv to create a Python virtual environment.
3. Run uv pip install httpx "mcp[cli]" to install dependencies.
4. Configure Claude Desktop by following the detailed steps in the section below.
5. Restart Claude Desktop and start exporting!

💬 First Command: "Using the servicenow-exporter, please export the incident table. My request ID is first-test-01."

🔧 Installation & Configuration

Step 1: Prepare Your Project

Make sure the project is on your computer and all its Python dependencies are installed. Open a terminal in the project directory and run:

• uv venv (This creates a local, isolated Python environment)
• uv pip install httpx "mcp[cli]" (This installs the necessary libraries)
• powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 2: Configure Claude Desktop

You need to tell Claude Desktop how to find and run the exporter. This involves editing a single configuration file.

• Find the configuration file:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Add the server configuration: Copy the JSON block below into the file. You must update the placeholder paths and your ServiceNow credentials to match your system.

{
    "mcpServers": {
        "servicenow-agent": {
            "command": "C:\\Users\\<YourUser>\\.local\\bin\\uv.exe",
            "args": [
                "--directory",
                "D:\\path\\to\\your\\project\\mcp-servicenow-exporter",
                "run",
                "python",
                "revised.py",
                "--instance-name", "YOUR_INSTANCE_NAME",
                "--username", "YOUR_SERVICENOW_USERNAME",
                "--password", "YOUR_SERVICENOW_PASSWORD"
            ]
        }
    }
}

Step 3: Restart Claude Desktop

Completely quit and restart the Claude Desktop application. This loads the new configuration and automatically starts your exporter server in the background.

💬 How to Use

Exporting data is a simple, two-step conversation. You start the job, and then you ask for the result when you're ready.

The Workflow

sequenceDiagram
    participant You
    participant Claude
    participant "Exporter Server" as Server

    You->>Claude: "Start export for 'incident' table with ID 'job-123'"
    Claude->>Server: Calls `export_table(...)`
    Server-->>Claude: "Acknowledged. Job started."
    Claude-->>You: "OK, I've started the export with ID 'job-123'."

    Note right of You: You can wait a few minutes...

    You->>Claude: "What is the status of job 'job-123'?"
    Claude->>Server: Calls `get_export_status(...)`
    Server-->>Claude: "Complete. File saved at C:\\Users\\...\\export.csv"
    Claude-->>You: "The export is finished! The file is in your Downloads folder at C:\\Users\\...\\export.csv"

Step 1: Start the Export

To begin, you must provide a unique request_id (to track your job) and the table name.

Your Prompt: "Using the servicenow-exporter, please export the incident table. My request ID is incident-export-2025-08-03."

Claude will confirm that the job has started.

Step 2: Check the Status and Get the File

After waiting a bit, ask for the status using the same request_id.

Your Prompt: "What is the status of export job incident-export-2025-08-03?"

• If the job is still running, you'll get a progress update.
• Once it's complete, Claude will give you a confirmation message with the full path to the file in your Downloads folder.

Advanced Example

You can also add a query and specify fields in your first prompt to customize the export.

Your Prompt: "Start an export from the cmdb_ci_server table with request ID active-linux-servers. I only want records where operational_status=1 and os is Linux. Please only include the name and ip_address fields."

🎛️ Available Tools

The MCP server provides two main tools for Claude to use:

• export_table: Starts a new, asynchronous export job.
• get_export_status: Checks the progress of an existing job and provides the file path upon completion.

🐛 Troubleshooting

• ModuleNotFoundError: No module named 'httpx': This means the required libraries are not installed in the environment the server is using. Ensure you have run uv pip install httpx "mcp[cli]" in your project's virtual environment and that the --directory path in your claude_desktop_config.json is correct.
• Server Fails to Start: Double-check all paths in your claude_desktop_config.json. They must be absolute paths, and the command path must point directly to your uv.exe file.
• Permission Denied Errors: If the export fails with a 401 or 403 error in the logs, verify that the username and password in your claude_desktop_config.json are correct and that the user has read permissions for the target table in ServiceNow.