README.md•3.4 kB
# 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