mcp-server-table 0.1.0

Model Context Protocol (MCP) server for AI-driven ServiceNow table data export to XML attachments.

🚀 ServiceNow MCP Server - AI-Powered Data Export Tool

🎯 Transform ServiceNow data access with natural language commands

Export ServiceNow table data effortlessly using voice commands and AI - no complex APIs needed!

🚀 Quick Start • 📖 Documentation • 💡 Examples • 🤝 Contributing

---

📋 Table of Contents

• 🌟 Overview
• ✨ Key Features
• 🏗️ Architecture
• ⚡ Quick Start
• 🔧 Installation
• ⚙️ Configuration
• 💡 Usage Examples
• 🎛️ Available Tools
• 📊 Supported Formats
• 🗺️ Table Mappings
• 🔒 Authentication
• 🐛 Troubleshooting
• 🤝 Contributing
• 📄 License

🌟 Overview

The ServiceNow MCP Server is a cutting-edge Model Context Protocol server that revolutionizes how you interact with ServiceNow data. By combining the power of AI with intuitive natural language processing, this tool transforms complex ServiceNow API operations into simple conversational commands.

graph TD
    A[👤 User Voice Command] --> B[🤖 Claude AI]
    B --> C[🔧 MCP Server]
    C --> D[🌐 ServiceNow API]
    D --> E[📊 Data Processing]
    E --> F[📁 File Export]
    F --> G[💾 Downloads Folder]

🎯 Why Choose ServiceNow MCP Server?

• 🗣️ Voice-Controlled: Use natural language commands instead of complex API calls
• 🧠 AI-Powered: Intelligent table name resolution from conversational descriptions
• ⚡ Lightning Fast: Optimized async operations for rapid data retrieval
• 🔒 Secure: Built-in authentication and error handling
• 📱 Cross-Platform: Works on Windows, macOS, and Linux
• 🎨 Multiple Formats: Export to CSV, XML, or both simultaneously

✨ Key Features

🎤 Natural Language Interface Convert "export server data" to actual table queries NEW: [table_name] bracket syntax support Command: "Export data from Server[cmdb_ci_server] table" Voice command support through Claude AI integration	📊 Smart Data Export Multiple export formats (CSV, XML, both) XML format as default (per requirements) Automatic file naming with timestamps File attachment support for Claude AI
🔧 Advanced API Support REST API integration (default) SOAP API support (new) 🚀 UNLIMITED RECORD EXPORT - Handles millions of records 📊 Pagination and chunked processing for memory efficiency Custom query filters with ServiceNow syntax Field selection for targeted exports	🛡️ Enterprise Ready Robust error handling and logging Secure authentication with environment variables Production-ready async architecture Cross-platform file handling

🏗️ Architecture

🔍 Click to expand architecture details

System Components

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude AI     │───▶│   MCP Server     │───▶│   ServiceNow    │
│                 │    │                  │    │                 │
│ • NL Processing │    │ • Table Mapping  │    │ • REST API      │
│ • Tool Calling  │    │ • Data Export    │    │ • Authentication│
│ • User Interface│    │ • File Generation│    │ • Data Storage  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │ Local File System│
                       │                  │
                       │ • Downloads Folder│
                       │ • CSV/XML Files  │
                       │ • Auto Naming    │
                       └──────────────────┘

Data Flow

1. Input: User provides natural language command
2. Processing: Claude AI interprets and calls appropriate MCP tool
3. Resolution: MCP server resolves table names and builds queries
4. Retrieval: Secure API calls to ServiceNow instance
5. Transformation: Data converted to requested format(s)
6. Output: Files saved to Downloads folder with confirmation

⚡ Quick Start

🚀 1-Minute Setup

# Clone the repository
git clone https://github.com/yourusername/servicenow-mcp-server.git
cd servicenow-mcp-server

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your ServiceNow credentials

# Run the server
python main.py

🎯 First Export

Once configured, try these natural language commands:

"Export the server table"

"Get me incident data in XML format"

"Export users with both CSV and XML"

🔧 Installation

Prerequisites

Requirement	Version	Purpose
Python	3.8+	Runtime environment
ServiceNow Instance	Any	Data source
Claude AI Access	Latest	Natural language interface

Step-by-Step Installation

📦 Detailed Installation Guide

1. Clone Repository

   git clone https://github.com/yourusername/servicenow-mcp-server.git
   cd servicenow-mcp-server
   

2. Create Virtual Environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install Dependencies

   pip install -r requirements.txt
   

4. Environment Setup

   cp .env.example .env
   

   Edit .env file:

   SERVICENOW_INSTANCE=https://your-instance.service-now.com
   SERVICENOW_USERNAME=your_username
   SERVICENOW_PASSWORD=your_password
   

5. Verify Installation

   python -c "import main; print('✅ Installation successful!')"
   

Requirements

# Core dependencies
fastmcp>=0.1.0
httpx>=0.24.0
python-dotenv>=1.0.0

# Optional enhancements
rich>=13.0.0        # Better console output
typer>=0.9.0        # CLI interface
pytest>=7.0.0       # Testing framework

⚙️ Configuration

Environment Variables

Variable	Description	Example	Required
SERVICENOW_INSTANCE	Your ServiceNow instance URL	https://dev12345.service-now.com	✅
SERVICENOW_USERNAME	ServiceNow username	admin	✅
SERVICENOW_PASSWORD	ServiceNow password	your_password	✅

🎤 Voice Commands

Command	Result	Format
"Export the server table"	➡️ cmdb_ci_server_export.csv	CSV
"Get incident data as XML"	➡️ incident_export.xml	XML
"Export users in both formats"	➡️ Both CSV & XML files	Both

📝 Detailed Examples

🔍 Click to see detailed examples

Basic Export

# Command: "Export the server table"
# Result: Downloads/cmdb_ci_server_export_20241201_143022.csv

Filtered Export

# Command: "Export active incidents from last week"
# Translates to query filter and exports matching records

Multi-Format Export

# Command: "Export user data in both CSV and XML"
# Creates:
# - Downloads/sys_user_export_20241201_143022.csv
# - Downloads/sys_user_export_20241201_143022.xml

Custom Fields

# Advanced usage through tool parameters:
# - table_description: "server table"
# - fields: "name,ip_address,sys_id"
# - max_records: 500

🔧 Primary Tools

Tool	Purpose	Input	Output
export_servicenow_data	🎯 Main export with bracket syntax	"[table_name] command"	XML attachment
export_with_bracket_syntax	📋 Specialized bracket parser	Bracket syntax command	XML file
export_table_to_xml	📄 Direct XML export	Table name	XML file
list_common_tables	📋 Show table mappings	None	Table reference

🆕 New Features for Unlimited Data Export

1. Unlimited Record Processing

# Now handles ANY number of records - 10K, 100K, 1M+
"Export ALL data from Server[cmdb_ci_server] table"
# Automatically uses pagination to fetch ALL records

2. Memory-Efficient Processing

# Chunked processing prevents memory overload
# - Fetches data in 1000-record chunks
# - Processes CSV in 5000-record chunks
# - Progress tracking for large datasets

3. Performance Optimizations

# Smart processing based on dataset size
# - Small datasets: Direct processing
# - Large datasets: Chunked processing with progress tracking
# - Memory management and garbage collection

4. Enterprise-Scale Support

# Production-ready for enterprise environments
# - Handles ServiceNow instances with millions of records
# - Automatic pagination and memory management
# - Robust error handling and recovery

🔒 Authentication

🛡️ Security Best Practices

✅ Recommended	❌ Avoid
Environment variables	Hardcoded credentials
Dedicated service account	Personal accounts
Minimal required permissions	Admin privileges
Regular password rotation	Static passwords

ServiceNow Permissions

Required roles and permissions:

• rest_service - Access REST APIs
• table_reader - Read table data
• Read access to target tables (e.g., cmdb_ci_server, incident)
• itil - For incident management tables

🔧 Detailed Permission Setup

1. Create Service Account

   Navigate to: User Administration > Users
   Create new user with appropriate roles
   

2. Assign Roles

   Required roles:
   - rest_service
   - table_reader
   - Custom roles for specific tables if needed
   

3. Test Access

   curl -u username:password \
     "https://your-instance.service-now.com/api/now/table/incident?sysparm_limit=1"
   

🐛 Troubleshooting

🔍 Common Issues

❌ Authentication Errors

Problem: HTTP 401 Unauthorized

Solutions:

• ✅ Verify credentials in .env file
• ✅ Check ServiceNow instance URL format
• ✅ Ensure account has required roles
• ✅ Test with ServiceNow's REST API Explorer

❌ Table Not Found

Problem: Table 'xyz' doesn't exist

Solutions:

• ✅ Use list_common_tables tool to see available mappings
• ✅ Check table name spelling
• ✅ Verify table exists in your instance
• ✅ Ensure read permissions on the table

❌ Export Failures

Problem: Export process fails or incomplete

Solutions:

• ✅ Check network connectivity
• ✅ Reduce max_records parameter
• ✅ Verify Downloads folder permissions
• ✅ Review ServiceNow instance performance

🔧 Debug Mode

Enable detailed logging:

export DEBUG=1
python main.py

📞 Support

Need help? Check these resources:

• [e-mail]

📋 Development Setup

🔧 Development Environment Setup

# Clone and setup
git clone https://github.com/yourusername/servicenow-mcp-server.git
cd servicenow-mcp-server

# Development environment
python -m venv dev-env
source dev-env/bin/activate  # Windows: dev-env\Scripts\activate

# Install dev dependencies
uv sync

📄 License

This project is licensed under the MIT License.

See the LICENSE file for details.

---

🌟 Made with ❤️ by Divya Shah

⭐ Star this repo • 🐛 Report Bug • ✨ Request Feature

---

Connect with me: