# ServiceNow CMDB MCP Server

A Model Context Protocol (MCP) server for interacting with ServiceNow CMDB (Configuration Management Database) tables.

## Features

- **Tool**: `get_cmdb_table_data` - Query any CMDB table with filtering, field selection, and pagination

## Installation for Claude

### Step 1: Setup the Server

1. **Navigate to the project directory**
   ```bash
   cd "ServiceNow CMDB MCP"
   ```

2. **Activate virtual environment**
   ```bash
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Configure ServiceNow credentials**
   ```bash
   cp .env.template .env
   ```
   
   Edit `.env` file with your ServiceNow instance details:
   ```env
   SERVICENOW_URL=https://your-instance.service-now.com
   SERVICENOW_USER=your-username
   SERVICENOW_PASS=your-password
   ```

4. **Start the MCP server**
   ```bash
   python server.py
   ```
   
   You should see: `INFO: Started server process` and `INFO: Uvicorn running on http://127.0.0.1:9123`

### Step 2: Configure Claude

1. **Open Claude settings** (gear icon in bottom left)

2. **Navigate to MCP section**

3. **Add the following configuration** to your `mcpServers` section:
   ```json
   "mcpServers": {
     "ServiceNowCMDB": {
       "command": "npx",
       "args": ["mcp-remote", "http://localhost:9123/mcp/"]
     }
   }
   ```

4. **Save and restart Claude**

### Step 3: Verify Installation

Once Claude restarts, you should see:
- A new "ServiceNowCMDB" server in your MCP servers list
- Access to the `get_cmdb_table_data` tool

### Prerequisites

- Python 3.11+
- Node.js and npm (for `npx` command)
- ServiceNow instance with API access
- Valid ServiceNow credentials

## Usage in Claude

After setup, you can use the tool in Claude:

```
Get all computers from CMDB:
Use get_cmdb_table_data with table_name="cmdb_ci_computer"

Get specific fields:
Use get_cmdb_table_data with table_name="cmdb_ci_computer" and fields="name,serial_number,manufacturer"

Filter by status:
Use get_cmdb_table_data with table_name="cmdb_ci_computer" and query="operational_status=1"
```

## API Endpoints

The server runs on `http://127.0.0.1:9123` by default.

### Tools

#### `get_cmdb_table_data`
Query any CMDB table with optional filtering and field selection.

**Parameters:**
- `table_name` (required): Name of the CMDB table
- `query` (optional): ServiceNow query string for filtering
- `fields` (optional): Comma-separated list of fields to return
- `limit` (optional): Maximum number of records (default: 100)
- `offset` (optional): Number of records to skip (default: 0)


## Usage Examples

### Get all computers
```python
await get_cmdb_table_data("cmdb_ci_computer")
```

### Get specific fields
```python
await get_cmdb_table_data(
    "cmdb_ci_computer",
    fields="name,serial_number,manufacturer"
)
```

### Filter by status
```python
await get_cmdb_table_data(
    "cmdb_ci_computer",
    query="operational_status=1"
)
```

## Common CMDB Tables

- `cmdb_ci_computer` - Computer configuration items
- `cmdb_ci_server` - Server configuration items
- `cmdb_ci_network_gear` - Network equipment
- `cmdb_ci_storage_device` - Storage devices
- `cmdb_ci_database` - Database configuration items

## Error Handling

The server includes comprehensive error handling for:
- Missing credentials
- HTTP errors from ServiceNow
- Invalid JSON responses
- Network timeouts

## License

MIT License