servicenow-devtools-mcp

ServiceNow Platform MCP

Connect your MCP client to an existing ServiceNow instance using public OAuth and local stdio transport.

Read records, explore metadata, inspect attachments and flows, search ServiceNow code, and investigate platform issues. With write tools explicitly enabled, you can also stage and apply record or attachment changes.

The server is built for developers and ServiceNow administrators. Your ServiceNow roles, REST policies, and ACLs still control what you can access.

Start here

You'll need Python 3.12+, uv, a ServiceNow instance, and an MCP client that can run local stdio servers.

1. Create a public OAuth application in ServiceNow using the authorization-code flow with PKCE and S256. Register this redirect URL:

   http://127.0.0.1:8765/oauth/callback
   

2. Copy the application's public client ID.

3. Add the server to your MCP client's configuration. Replace the instance URL and public client ID with your own:

   {
     "mcpServers": {
       "servicenow-platform": {
         "command": "uvx",
         "args": [
           "servicenow-platform-mcp"
         ],
         "env": {
           "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
           "SERVICENOW_OAUTH_CLIENT_ID": "your-public-client-id",
           "MCP_TOOL_PACKAGE": "readonly",
           "SERVICENOW_ENV": "dev"
         }
       }
     }
   }
   

4. Restart the MCP client and call list_tool_packages.

5. Try a small read request. The first request to ServiceNow opens your default browser and asks you to authorize access.

Run the browser and MCP server on the same machine. Use uvx servicenow-platform-mcp for the newest available release.

Install in your AI client

Choose the setup below for your client and replace the instance URL and public client ID. Each example starts with the readonly tool package.

Claude Code

Add the server to your Claude Code user configuration:

claude mcp add \
  --scope user \
  --transport stdio \
  servicenow-platform \
  --env SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com \
  --env SERVICENOW_OAUTH_CLIENT_ID=your-public-client-id \
  --env MCP_TOOL_PACKAGE=readonly \
  --env SERVICENOW_ENV=dev \
  -- uvx servicenow-platform-mcp

Run claude mcp list to check that the server was added.

GitHub Copilot in VS Code

Create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "servicenow-platform": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "servicenow-platform-mcp"
      ],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_OAUTH_CLIENT_ID": "your-public-client-id",
        "MCP_TOOL_PACKAGE": "readonly",
        "SERVICENOW_ENV": "dev"
      }
    }
  }
}

Restart VS Code, then trust and start the server when Copilot prompts you.

OpenCode

For a single project, add the server to opencode.json in the project root. To use it across all projects, add it to ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servicenow-platform": {
      "type": "local",
      "command": [
        "uvx",
        "servicenow-platform-mcp"
      ],
      "environment": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_OAUTH_CLIENT_ID": "your-public-client-id",
        "MCP_TOOL_PACKAGE": "readonly",
        "SERVICENOW_ENV": "dev"
      }
    }
  }
}

Restart OpenCode to load the server.

Keep API keys, Basic Auth credentials, passwords, client secrets, access tokens, authorization codes, and PKCE verifiers out of your client configuration.

Configure ServiceNow OAuth

In ServiceNow, open System OAuth > Application Registry. Create an application for this server, or open an existing one, and use these settings:

Setting	Value
Public Client	true
Authorization flow	Authorization code with PKCE
PKCE method	S256
Scope	useraccount
Redirect URL	http://127.0.0.1:8765/oauth/callback

Save the application and copy its public client ID into SERVICENOW_OAUTH_CLIENT_ID. The default scope is useraccount. Only set SERVICENOW_OAUTH_SCOPE if your application has a different scope enabled.

When an access token expires, the server renews it using the issued refresh token. No client secret is needed. Tokens stay in process memory, so you'll need to authorize again in the browser each time you restart the MCP server.

OAuth authenticates the user. It does not grant table access. Every request still follows the authorized user's REST API policies, roles, table ACLs, field ACLs, and row visibility rules.

Choose a tool package

Use MCP_TOOL_PACKAGE to choose which tools the server loads:

Package	Includes	Recommended use
readonly	Records, metadata, attachments, investigations, analysis, audits, flows, code search, and CMDB	Normal read-only work
core_readonly	query, describe, and read-only attachment	Minimal inspection access
full	Every tool group, including record and attachment writes	Controlled write workflows
none	Only list_tool_packages	Test client connectivity

For more control, list the tool groups you need, separated by commas:

MCP_TOOL_PACKAGE=query,describe,record_read,attachment

Available groups are query, describe, record_write, record_read, attachment, attachment_write, investigate, resolve_choice, service_catalog, analysis, audit, flow, code_search, and cmdb.

A tool package controls which tools are loaded, not what you're allowed to do. ServiceNow still checks authorization for each request.

Make your first requests

Use query to fetch a limited set of records. This example requests up to 10 active incidents:

{
  "table": "incident",
  "fields": "sys_id,number,short_description,state",
  "encoded_query": "active=true",
  "limit": 10,
  "display_values": true
}

Use record_read to fetch a single record. Provide either sys_id or name, but not both:

{
  "table": "incident",
  "sys_id": "32-character-sys-id",
  "fields": "sys_id,number,short_description,state"
}

For an unfamiliar table, start with describe:

{
  "table": "incident",
  "include_docs": true
}

These examples require read access to the incident table. Replace it with a table the authorized user can read if needed. For a tool's complete input details, use its describe action when available.

Configure from a local checkout

To work on the server locally or run it from source, clone the repository and install its dependencies:

git clone https://github.com/Xerrion/servicenow-platform-mcp.git
cd servicenow-platform-mcp
uv sync --group dev

Create .env.local in the directory where the MCP client starts the server:

SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com
SERVICENOW_OAUTH_CLIENT_ID=your-public-client-id
MCP_TOOL_PACKAGE=readonly
SERVICENOW_ENV=dev

Configure your client to run uv run servicenow-platform-mcp with the checkout as its working directory.

The server reads .env first, then .env.local, from that directory. Process environment variables override values from both files. Keep both dotenv files out of version control.

Write safely

To enable writes, use full or a custom package that includes record_write or attachment_write. The authorized ServiceNow user also needs permission to make those changes.

Record writes are previewed before they're applied. Pass the one-time preview_token from the preview to record_apply to apply the change.

Set SERVICENOW_ENV=prod or SERVICENOW_ENV=production to block local writes. For a read-only setup, combine a read-only ServiceNow user with GET-only REST API policies and MCP_TOOL_PACKAGE=readonly.

Troubleshooting

Problem	What to check
Configuration fails at startup	Check that the environment variable names match exactly. Make sure the client passes them to the server, or starts it in the directory containing the intended dotenv file.
Browser does not open	Check that a browser is available on the machine running the MCP server.
Authorization times out	Run the browser and server on the same machine. Check that the redirect URL exactly matches the one in the Application Registry.
OAuth token exchange is rejected	Check public-client mode, PKCE S256, the client ID, the enabled scope, and the redirect URL.
HTTP 401 or User Not Authenticated	Authorize again on the next call. If the error continues, check scopes, REST API policies, and the user's access.
HTTP 403	Check REST resource permissions, roles, table ACLs, and field ACLs.
Configuration changes do not apply	Restart the MCP server process.
No module named httpx2 in a source checkout	Run uv sync --group dev again. The server uses httpx2, not httpx.
Write preview token not found after upgrade	Previews are memory-only. Create the preview again after the restart.

Security

• Grant only the access needed through ServiceNow roles, REST policies, table ACLs, and field ACLs.
• Use readonly or a smaller custom package wherever possible.
• Keep API keys, Basic Auth credentials, passwords, and client secrets out of the configuration.
• Never log or commit access tokens, authorization codes, PKCE verifiers, or callback URLs containing query strings.
• Treat attachments and other ServiceNow content as untrusted data.

Reference

• Installation guide: full configuration details, permissions, OAuth behavior, and guidance for running the server
• PyPI package
• MCP stdio transport
• uv tool guide