MCP 客户端配置

各 MCP 客户端的详细安装说明。所有客户端使用同一个 MCP 服务器 —— 只是配置格式不同。

从这里开始： uvx 是所有平台上的默认安装方式。如果 uvx 跑不起来 —— 通常是 Windows 智能应用控制（Smart App Control）所致 —— 请改用 pip。安装路径就这两条。

---

开始之前

默认使用 uvx。它能让 macOS、Linux 和 Windows 上的安装与客户端配置保持一致。

1. 安装 uv

macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. 获取服务器 + 安装 Chromium

uvx --refresh --with playwright --from mfa-servicenow-mcp servicenow-mcp --version  # 获取并验证服务器
uvx --with playwright playwright install chromium                                   # 用于 MFA/SSO 登录的 Chromium

第一条命令会在客户端所使用的完全相同的 --with playwright 环境中预取并验证服务器，使首次启动瞬间完成。第二条命令下载 Chromium；如果标准缓存中已有匹配的 Chromium，uvx 会复用它。

如果 uvx 被阻止 —— 改用 pip

Windows 智能应用控制会让 uvx 完全无法运行：uvx 每次运行都会解压出一个未签名的临时可执行文件，而 SAC 会拦截它。如果 uvx 是在某次 Windows 更新之后突然不能用了，基本就是这个原因。此时请改用 pip 安装：

pip install mfa-servicenow-mcp playwright
python -m playwright install chromium

来自 python.org 安装程序的 Python（已签名，3.10+）可直接通过 SAC 检查。启动服务器请使用 python -m servicenow_mcp —— 不要用 servicenow-mcp 命令行脚本，它是 pip 生成的未签名 .exe 包装器，同样会被 SAC 拦截。

在 macOS/Linux 上，pip 唯一需要注意的是 Homebrew 和发行版自带的 Python 会按 PEP 668 拒绝全局安装（externally-managed-environment）。请改用 python.org 的安装程序，或干脆继续用 uvx。

如果连 PyPI 本身都无法访问 —— 企业网络屏蔽了包索引 —— 那么两条路径都拿不到这个包。请让 IT 将 pypi.org 和 files.pythonhosted.org 加入白名单，或者在内部索引上做镜像，再用 pip install --index-url 指向它。

Windows 用户：分步细节及代理/杀毒软件注意事项请参阅 Windows 安装指南。

3. 将服务器添加到你的 MCP 客户端配置

向客户端的配置文件中添加一个条目（无需安装命令）。无论用哪种方式安装，env 块都完全相同 —— 只有 command/args 随你上面选择的路径而变：

安装方式	command	args
uvx（默认）	uvx	["--with","playwright","--from","mfa-servicenow-mcp","servicenow-mcp"]
pip（uvx 被阻止时）	python	["-m","servicenow_mcp"]

下文各客户端示例一律采用 uvx 形式。使用 pip 时，只需替换这两个键，其余保持不变。

{
  "mcpServers": {
    "servicenow": {
      "command": "uvx",
      "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser"
      }
    }
  }
}

各客户端的文件路径和格式（Codex TOML 等）见下文；之后请重启客户端。

快速测试

在配置客户端之前先验证服务器能否启动：

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

# pip 安装：把第一行替换为
python -m servicenow_mcp \
  --instance-url "https://your-instance.service-now.com" \
  --auth-type "browser" \
  --browser-headless "false"

如果服务器启动并打开一个用于登录的浏览器窗口，就可以按下文配置你的客户端了。

---

配置指南

args 仅用于包本身 —— 实例 URL、认证、凭据全部放在 env（或 environment）中。这能让 args 保持简洁，并便于为每个项目切换实例。

推荐使用项目本地配置：使用项目范围的配置，让每个项目都能连接到不同的 ServiceNow 实例。

下面变化的只有 env 里的内容。command/args 保持步骤 3 中的样子即可 —— 无论你走的是哪条安装路径。

配置文件（profiles）—— 从这里开始

如果你要接触不止一个 ServiceNow 实例，请配置 profiles，而不是为每个实例各起一个服务器。 给每个环境取一个别名，再选出活动的那个：

      "env": {
        "MCP_TOOL_PACKAGE": "standard",
        "SERVICENOW_ACTIVE_INSTANCE": "dev",
        "SERVICENOW_INSTANCE_CONFIG": "{ \"dev\": { \"url\": \"https://acme-dev.service-now.com\", \"auth_type\": \"browser\", \"allow_writes\": true }, \"test\": { \"url\": \"https://acme-test.service-now.com\", \"auth_type\": \"browser\", \"allow_writes\": true }, \"prod\": { \"url\": \"https://acme-prod.service-now.com\", \"auth_type\": \"browser\" } }"
      }

这一个块就替代了 SERVICENOW_INSTANCE_URL，本指南其余部分也都建立在它之上：

• 生产靠"不写"来保护。 没有 allow_writes 的别名就是只读的。上面的 prod 根本无法写入 —— 忘记加某个标志永远不会意外打开生产写入。
• 不重启就能访问另一个实例。 读取类工具接受 instance 参数：在 dev 保持活动的同时执行 sn_query(instance="prod", …)。
• 直接比较环境。 compare_instances 对同一条记录在两个别名之间做差异比较；list_instances 列出每个别名及其写入标志。
• 只需一次浏览器登录。 会话在各别名之间共享，而不是每个服务器进程各登录一次。
• 写入非活动实例受保护，绝不静默 —— 路由规则、confirm_instance 关卡以及 ${ENV} 密钥引用见多实例模式。

单实例

只有一个实例？那就完全跳过 profiles —— 两个变量就是全部配置：

      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser"
      }

这种写法仍然有效，也没有被废弃；它只是上面 profile 配置的最简形式。

一个连接还是多个？

Profiles 把所有实例都放在一个客户端连接后面，这也是绝大多数人想要的。如果你确实需要在客户端 UI 里视觉上彼此分开的连接 —— 比如各自独立的 snow-dev 和 snow-prd 条目 —— 请见为多个服务器条目命名。但那会失去 compare_instances、共享登录和 allow_writes 开关，所以只在确实需要 UI 分离时才这么选。

---

Streamable HTTP

默认传输方式是 stdio。对于远程 MCP 客户端或本地 HTTP 桥接，使用 Streamable HTTP 启动服务器：

servicenow-mcp --transport http --http-host 127.0.0.1 --http-port 8000
# pip 安装：python -m servicenow_mcp --transport http --http-host 127.0.0.1 --http-port 8000

MCP 端点为 http://127.0.0.1:8000/mcp；/health 返回一个轻量级状态响应。除非服务器处于受信任的网络管控之后，否则请保持默认的回环主机。

---

多实例模式（比较 + 受保护的单次调用写入）

通过 SERVICENOW_INSTANCE_CONFIG 配置命名实例（例如 dev / test / prod 别名），使一个会话既能跨环境比较，又能部署到选定的实例 —— 无需切换活动实例或重启服务器。用 instance=<alias> 参数路由单次调用：

• 只读调用可自由路由：instance=test 会在 dev 保持活动时读取 test。
• 向非活动实例的写入是允许的，但绝不会静默。那一次调用必须命名目标并予以批准 —— instance=test confirm_instance=test confirm=approve —— 且目标必须设有 allow_writes=true。只有那一次写入会被路由到那里；紧接着活动实例即被恢复。目标/confirm 不匹配或只读目标会以明确消息被拒绝，因此 dev/test/prod 混淆不会落到错误的实例上。
• 写入会在目标实例上验证。 结果会回显 target_instance 和 landed 判定：工具会在目标实例上重新读取已推送的字段，若内容未持久化（例如 sp_* Service Portal 字段被静默丢弃）则返回 WRITE_NOT_LANDED。"成功"意味着内容已确认存在于目标实例上 —— 而不仅仅是请求返回了 200。
• compare_instances 跨别名比较记录（只读）；list_instances 报告已配置的别名及各自的写入标志。
• 除非你有意进行生产写入，否则请将 prod 保持在 allow_writes=false —— 这样即使忘记该标志也绝不会启用生产写入。

对于批量记录的推广（尤其是 Service Portal / scoped 表），相比逐记录的跨实例写入，更推荐使用 Update Set —— 在源实例 commit，在目标 UI 中 retrieve + commit —— 它可以绕过单次 Table-API 写入会碰到的 per-table/SP ACL。

SERVICENOW_ACTIVE_INSTANCE=dev
SERVICENOW_INSTANCE_CONFIG='{
  "dev":  { "url": "https://acme-dev.service-now.com",  "auth_type": "browser", "allow_writes": true },
  "test": { "url": "https://acme-test.service-now.com", "auth_type": "browser", "allow_writes": true },
  "prod": { "url": "https://acme-prod.service-now.com", "auth_type": "browser", "allow_writes": false }
}'

各实例的凭据放在 MCP 客户端的 env 块中（每个别名都可携带自己的 username / password / auth_type / api_key；${ENV} 让密钥不出现在 JSON 中；单实例的 SERVICENOW_INSTANCE_URL 形式仍可作为回退）：

{
  "mcpServers": {
    "servicenow": {
      "command": "uvx",
      "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"],
      "env": {
        "MCP_TOOL_PACKAGE": "standard",
        "SERVICENOW_ACTIVE_INSTANCE": "dev",
        "SERVICENOW_INSTANCE_CONFIG": "{ \"dev\": { \"url\": \"https://acme-dev.service-now.com\", \"auth_type\": \"browser\", \"username\": \"dev_user\", \"password\": \"${SERVICENOW_DEV_PASSWORD}\", \"allow_writes\": true }, \"test\": { \"url\": \"https://acme-test.service-now.com\", \"auth_type\": \"browser\", \"username\": \"test_user\", \"password\": \"${SERVICENOW_TEST_PASSWORD}\" } }"
      }
    }
  }
}

比对示例：

{
  "source": "dev",
  "target": "test",
  "table": "sys_script_include",
  "key_field": "api_name",
  "fields": "api_name,name,active,script",
  "query": "sys_scope.scope=x_company_app"
}

对非活动实例的单次写入，请使用上面受保护的 instance=<alias> confirm_instance=<alias> confirm=approve 路由。批量提升多条记录时，优先使用 Update Set，而非逐条的跨实例写入。

---

为多个服务器条目命名（--server-name）

这是与上面多实例模式不同的拓扑结构。多实例 = 一个连接即可访问多个实例；本节 = 多个彼此独立的连接，每个实例一个进程，各自固定连向自己的实例 —— 只有当你希望 dev/stg/prd 在客户端界面中明显分开时才值得这么做。

麻烦之处在于：每个条目默认都以 ServiceNow 自称，因此客户端只能按加载顺序来区分它们 —— mcp_servicenow、mcp_servicenow2、mcp_servicenow3。这个编号可能在重启之间发生变化，因此用它来判断哪个连接是生产环境并不可靠。 请用 --server-name 给每个条目起个名字：

{
  "mcpServers": {
    "snow-dev": {
      "command": "uvx",
      "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp", "--server-name", "snow-dev"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://acme-dev.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser"
      }
    },
    "snow-prd": {
      "command": "uvx",
      "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp", "--server-name", "snow-prd"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://acme.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

这样工具名就固定为 mcp_snow-dev_* / mcp_snow-prd_*。环境变量 SERVICENOW_MCP_SERVER_NAME 效果相同，两者同时设置时以命令行参数为准。不设置时名称仍为 ServiceNow，因此已有配置照常可用。

能用配置文件（profile）就优先用它。 如果只是要在一个连接内切换实例，推荐使用多实例模式：只有它才提供 compare_instances、共享的单次浏览器登录，以及按别名生效的 allow_writes 开关。独立进程这些都没有 —— 每个进程只知道自己的实例、各自单独登录，而挡在你和一次生产写入之间的，就只剩工具包这一道防线。

---

Claude Desktop

范围	路径
全局	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
全局	%APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "servicenow": {
      "command": "uvx",
      "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser",
        "SERVICENOW_BROWSER_HEADLESS": "false",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

Claude Desktop 不支持项目本地配置。如需按项目设置，请使用 Claude Code。

---

Claude Code

范围	路径
全局	~/.claude.json
项目	项目根目录下的 .mcp.json

{
  "mcpServers": {
    "servicenow": {
      "command": "uvx",
      "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser",
        "SERVICENOW_BROWSER_HEADLESS": "false",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

---

Zed

范围	路径
全局	~/.config/zed/settings.json

在 Zed 中通过 Settings > MCP Servers 添加：

{
  "servicenow": {
    "command": "uvx",
    "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"],
    "env": {
      "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
      "SERVICENOW_AUTH_TYPE": "browser",
      "SERVICENOW_BROWSER_HEADLESS": "false",
      "SERVICENOW_USERNAME": "your-username",
      "SERVICENOW_PASSWORD": "your-password",
      "MCP_TOOL_PACKAGE": "standard"
    }
  }
}

---

OpenAI Codex（CLI 与 App）

Codex CLI（codex 命令）和 Codex App（chatgpt.com/codex）都从同一个 config.toml 读取配置。

范围	路径	备注
全局	~/.codex/config.toml	所有项目共享
项目	.codex/config.toml	覆盖全局（仅限受信任的项目）

[mcp_servers.servicenow]
command = "uvx"
args = ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"]
enabled = true

[mcp_servers.servicenow.env]
SERVICENOW_INSTANCE_URL = "https://your-instance.service-now.com"
SERVICENOW_AUTH_TYPE = "browser"
SERVICENOW_BROWSER_HEADLESS = "false"
SERVICENOW_USERNAME = "your-username"
SERVICENOW_PASSWORD = "your-password"
MCP_TOOL_PACKAGE = "standard"
# 登录会在各主机间自动共享（在 ~/.mfa_servicenow_mcp 下按实例 + 用户
# 进行范围隔离）。仅当某个沙箱化主机重映射了 HOME 时才设置
# SERVICENOW_BROWSER_USER_DATA_DIR —— 见 README 的 "Login sharing" 说明。运行
# 多个实例时不要设置它；它会把多个实例合并到同一个 Chromium 配置文件中。

---

OpenCode

范围	路径
项目	项目根目录下的 opencode.json

OpenCode 使用 environment（而非 env）。

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servicenow": {
      "type": "local",
      "command": ["uvx", "--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"],
      "enabled": true,
      "environment": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser",
        "SERVICENOW_BROWSER_HEADLESS": "false",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

---

AntiGravity

范围	路径
全局	~/.gemini/antigravity/mcp_config.json (macOS/Linux)
全局	%USERPROFILE%\.gemini\antigravity\mcp_config.json (Windows)

通过代理面板编辑：... > Manage MCP Servers > View raw config。保存后点击 Refresh。

{
  "mcpServers": {
    "servicenow": {
      "command": "uvx",
      "args": ["--with", "playwright", "--from", "mfa-servicenow-mcp", "servicenow-mcp"],
      "env": {
        "SERVICENOW_INSTANCE_URL": "https://your-instance.service-now.com",
        "SERVICENOW_AUTH_TYPE": "browser",
        "SERVICENOW_BROWSER_HEADLESS": "false",
        "SERVICENOW_USERNAME": "your-username",
        "SERVICENOW_PASSWORD": "your-password",
        "MCP_TOOL_PACKAGE": "standard"
      }
    }
  }
}

---

Docker（仅 API 密钥）

浏览器认证（MFA/SSO）需要图形界面浏览器，无法在容器内工作。

docker run -it --rm \
  -e SERVICENOW_INSTANCE_URL=https://your-instance.service-now.com \
  -e SERVICENOW_AUTH_TYPE=api_key \
  -e SERVICENOW_API_KEY=your-api-key \
  -e MCP_TOOL_PACKAGE=standard \
  ghcr.io/jshsakura/mfa-servicenow-mcp:latest