Metadata-Version: 2.4
Name: mfa-servicenow-mcp
Version: 1.0.3
Summary: A Model Context Protocol (MCP) server implementation for ServiceNow
Author: ServiceNow MCP Contributors
License: MIT License
        
        Copyright (c) 2025 100x Technology Inc
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.11
Requires-Dist: httpx>=0.24.0
Requires-Dist: mcp[cli]==1.3.0
Requires-Dist: playwright>=1.44.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.28.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: uvicorn>=0.22.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort==5.13.2; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.0.1; extra == 'dev'
Description-Content-Type: text/markdown

# ServiceNow MCP Server

[English](./README.md) | [한국어](./README.ko.md)

ServiceNow MCP server with browser-based authentication for MFA/SSO environments. It is designed for direct use from MCP clients such as Claude Desktop, OpenCode, Gemini Code Assist, and similar local MCP hosts.

[![Python Version](https://img.shields.io/pypi/pyversions/mfa-servicenow-mcp)](https://pypi.org/project/mfa-servicenow-mcp/)
[![PyPI version](https://img.shields.io/pypi/v/mfa-servicenow-mcp.svg)](https://pypi.org/project/mfa-servicenow-mcp/)

## Quick Start

Most users do not need to clone this repository. If you have [uv](https://astral.sh/uv), you can register the server directly in your MCP client.

### Claude Desktop

Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "servicenow": {
      "command": "uvx",
      "args": [
        "mfa-servicenow-mcp",
        "--instance-url",
        "https://your-instance.service-now.com",
        "--auth-type",
        "browser",
        "--browser-headless",
        "false"
      ]
    }
  }
}
```

### OpenCode / Gemini / Vertex AI

```json
{
  "mcp": {
    "servicenow": {
      "type": "local",
      "command": [
        "uvx",
        "mfa-servicenow-mcp",
        "--instance-url",
        "https://your-instance.service-now.com",
        "--auth-type",
        "browser",
        "--browser-headless",
        "false"
      ],
      "enabled": true
    }
  }
}
```

### Run Directly From a Terminal

```bash
uvx mfa-servicenow-mcp --instance-url "https://your-instance.service-now.com" --auth-type "browser"
```

Notes:
- The first run may install browser dependencies automatically.
- Browser auth may open a login window.
- Use `--browser-headless false` if you want an interactive MFA/SSO flow.

### Install as a Local Command

```bash
uv tool install mfa-servicenow-mcp
servicenow-mcp --instance-url "https://your-instance.service-now.com" --auth-type "browser"
```

Windows users can also use [WINDOWS_INSTALL.md](./WINDOWS_INSTALL.md).

## Features

- Browser authentication for MFA/SSO environments
- Safe write confirmation with `confirm='approve'`
- Payload safety limits and truncation for large records
- Tool packages for standard users, service desk, portal developers, and platform developers
- Developer-focused tools for logs, source lookup, workflow inspection, and update set operations

## Authentication

Choose the auth mode based on your ServiceNow environment.

### Browser Auth

Use this for Okta, Entra ID, SAML, MFA, or any interactive SSO flow.

```bash
uvx mfa-servicenow-mcp \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type "browser" \
  --browser-headless "false"
```

Optional browser-related flags:
- `--browser-username`
- `--browser-password`
- `--browser-user-data-dir`
- `--browser-timeout`
- `--browser-probe-path`

Environment variables:

```env
SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_AUTH_TYPE=browser
SERVICENOW_BROWSER_HEADLESS=false
```

### Basic Auth

Use this for PDIs or instances without MFA.

```bash
uvx mfa-servicenow-mcp \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type "basic" \
  --username "your_id" \
  --password "your_password"
```

### OAuth

Current CLI support expects OAuth password grant inputs.

```bash
uvx mfa-servicenow-mcp \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type "oauth" \
  --client-id "your_client_id" \
  --client-secret "your_client_secret" \
  --username "your_id" \
  --password "your_password"
```

If `--token-url` is omitted, the server defaults to `https://<instance>/oauth_token.do`.

### API Key

```bash
uvx mfa-servicenow-mcp \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type "api_key" \
  --api-key "your_api_key"
```

Default header: `X-ServiceNow-API-Key`

## Tool Packages

Set `MCP_TOOL_PACKAGE` to choose a smaller tool set. Default: `standard`

| Package | Intended Use | Highlights |
| :--- | :--- | :--- |
| `standard` | General users | Incidents, catalog, knowledge, core queries |
| `portal_developer` | Portal developers | Portal code, script includes, safe logs, source lookup, workflow read, update set commit/publish |
| `platform_developer` | Platform developers | Script includes, safe logs, source lookup, workflows, UI policy, change set management |
| `service_desk` | Operations | Incident handling, comments, user lookup, article lookup |
| `full` | Admin / unrestricted read surface | Broad access across all implemented tool domains |

## Safety Policy

All mutating tools are protected by explicit confirmation.

Rules:
1. Tools such as `create_`, `update_`, `delete_`, `execute_`, `add_`, `commit_`, and `publish_` require confirmation.
2. You must pass `confirm='approve'`.
3. Without that parameter, the server rejects the request before execution.

This policy applies regardless of the selected tool package.

## Developer Setup

If you want to modify the source locally:

```bash
git clone https://github.com/jshsakura/mfa-servicenow-mcp.git
cd mfa-servicenow-mcp

uv venv
uv pip install -e .
uv run playwright install chromium
```

For Windows-specific setup, see [WINDOWS_INSTALL.md](./WINDOWS_INSTALL.md).

## Documentation

- [Catalog Guide](docs/catalog.md)
- [Change Management Guide](docs/change_management.md)
- [Workflow and Developer Tools](docs/workflow_management.md)
- [Korean README](./README.ko.md)

## Related Projects and Acknowledgements

- This repository includes tools that were consolidated and refactored from earlier internal / legacy ServiceNow MCP implementations. You can still see that lineage in modules such as [core_plus.py](./src/servicenow_mcp/tools/core_plus.py) and [tool_utils.py](./src/servicenow_mcp/utils/tool_utils.py).
- Some developer productivity workflows, especially server-side source lookup, were designed with ideas inspired by [SN Utils](https://github.com/arnoudkooi/SN-Utils). This project does not bundle or redistribute SN Utils code. It implements MCP-oriented server tools separately.
- This project is focused on MCP server use cases rather than browser-extension UX. If you want in-browser productivity features directly inside ServiceNow, SN Utils remains a strong companion tool.

## License

MIT License
