Salesforce

salesforce-mcp

面向 Salesforce CRM 的 MCP（Model Context Protocol）服务，专用于 WYRE Gateway BYOC 用例。

一个专注的 HTTP MCP 服务，通过 WYRE MCP Gateway 向 Claude（以及其他 MCP 客户端）开放 Salesforce 组织的 CRM 数据。专为多租户网关模式构建：凭据通过 HTTP 请求头按请求注入，不会将启动密钥写入容器。

范围约束

此软件包有意提供精简的工具集——六个 CRM 数据工具，并刻意省略了更广泛的 Salesforce MCP 服务所包含的 Apex 代码管理、自定义对象创建和 EXECUTE_ANONYMOUS 功能。此用例面向标准 CRM 对象（Accounts、Contacts、Opportunities、Leads、Cases）的读写访问。需要 DX 或管理工具的客户应改用官方的 @salesforce/mcp 软件包。

工具

工具	用途
salesforce_search_objects	按部分名称查找标准对象和自定义对象。
salesforce_describe_object	获取对象的完整架构（字段、选项列表、关系）。
salesforce_query_records	执行支持关系遍历的 SOQL。
salesforce_aggregate_query	执行 SOQL GROUP BY / COUNT / SUM / AVG / MIN / MAX。
salesforce_dml_records	插入、更新、删除或 upsert 记录。
salesforce_search_all	跨对象 SOSL 搜索。

运行模式

• http（默认）：监听 :8080，开放 /mcp（JSON-RPC）和 /health。凭据通过每个请求中的 X-Salesforce-* 请求头提供。这是网关部署模式。除非 CONDUIT_S2S_SECRET 是有效密钥，否则 HTTP 模式不会启动。
• stdio：传统 MCP 客户端传输方式（Claude Desktop / Cursor）。凭据从环境变量中读取一次。stdio 传输方式不使用 CONDUIT_S2S_SECRET。

复制 .env.example，并设置以下变量。请将该文件中的 CONDUIT_S2S_SECRET 留空。

变量	必需	描述
SALESFORCE_CLIENT_ID / SALESFORCE_CLIENT_SECRET / SALESFORCE_INSTANCE_URL	用于 stdio 和 AUTH_MODE=env	客户端凭据流。
SALESFORCE_USERNAME / SALESFORCE_PASSWORD / SALESFORCE_TOKEN	用于用户名和密码认证	当 SALESFORCE_AUTH_FLOW=username_password 时使用。如果组织使用 IP 允许列表，令牌可选。
MCP_TRANSPORT	否	http（默认）或 stdio。
AUTH_MODE	否	gateway（镜像和 Compose 的默认值）或 env。Gateway 模式要求每个 /mcp 请求都包含 X-Salesforce-* 请求头，且不会回退到 SALESFORCE_*。只有在 S2S 身份验证成功后，env 模式才会使用这些变量。
CONDUIT_S2S_SECRET	HTTP 模式下必需	服务间密钥。如果该值为空或是已知占位符（changeme、placeholder、your-s2s-secret、secret、password、test、未解析的 ${...} 模板，以及 src/s2s-verify.ts 中的其他占位值），HTTP 会记录错误并以非零状态码退出。切勿提交真实密钥。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设置为精确值 1，以便在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会检查 X-Gateway-S2S，并且只监听 127.0.0.1。非环回地址的 MCP_HTTP_HOST 会被忽略，并记录相应覆盖信息。若设置的是已知占位符密钥，仍会拒绝启动。
MCP_HTTP_HOST	否	设置了可用的 CONDUIT_S2S_SECRET 时使用的绑定地址。未设置时，若已配置密钥，则使用 HOST（默认为 0.0.0.0）。没有可用密钥时，监听地址为 127.0.0.1。容器镜像将其设为 0.0.0.0。
PORT	否	HTTP 端口。默认为 8080。
HOST	否	设置了密钥但未设置 MCP_HTTP_HOST 时使用的备用绑定地址。默认为 0.0.0.0。

/health 不需要身份验证，也不会读取凭据。

# HTTP mode (exits unless CONDUIT_S2S_SECRET is a real secret)
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" PORT=8080 MCP_TRANSPORT=http AUTH_MODE=gateway npm start

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_TRANSPORT=http npm start

# stdio mode (env-baked, local testing; no S2S secret)
MCP_TRANSPORT=stdio \
SALESFORCE_AUTH_FLOW=client_credentials \
SALESFORCE_CLIENT_ID=... SALESFORCE_CLIENT_SECRET=... \
SALESFORCE_INSTANCE_URL=https://yourorg.my.salesforce.com \
node dist/entry.js

请求头约定（网关模式）

设置 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含有效的 X-Gateway-S2S 请求头。网关模式还要求提供所选流程对应的凭据请求头。缺少这些请求头的请求会返回 401，且不会回退到进程环境中的 SALESFORCE_*。

请求头	是否必需？	说明
X-Gateway-S2S	设置 S2S 密钥后必需	t=<unix seconds>,v1=<hex hmac-sha256>。请参阅 X-Gateway-S2S 签名。
X-Salesforce-Auth-Mode	可选	client_credentials（默认）或 username_password。
X-Salesforce-Client-Id	使用 client_credentials 时必需	Connected App 消费者密钥。
X-Salesforce-Client-Secret	使用 client_credentials 时必需	Connected App 消费者机密。
X-Salesforce-Instance-Url	使用 client_credentials 时必需	客户的 My Domain URL（例如 https://acmecorp.my.salesforce.com）。
X-Salesforce-Username	使用 username_password 时必需	Salesforce 用户名。
X-Salesforce-Password	使用 username_password 时必需	Salesforce 密码。
X-Salesforce-Token	使用 username_password 时必需	安全令牌（除非 IP 已加入允许列表，否则必需）。

按请求进行身份验证意味着同一个容器实例可以为许多客户提供服务，而无需重启——每个 MCP tools/call 都会根据该请求中的请求头创建新的 jsforce.Connection。

X-Gateway-S2S 签名

v1 是 t=<unix seconds>（即请求头开头的同一个 t= 前缀）这一 ASCII 字符串的 HMAC-SHA256 十六进制编码，密钥为 CONDUIT_S2S_SECRET。时间戳必须在服务器时钟的前后 300 秒内。缺少或无效的请求头会返回 HTTP 401。密钥绝不会写入日志或响应正文。

t=$(date +%s)
v1=$(printf 't=%s' "$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${t},v1=${v1}" \
  -H "X-Salesforce-Client-Id: ..." \
  -H "X-Salesforce-Client-Secret: ..." \
  -H "X-Salesforce-Instance-Url: https://yourorg.my.salesforce.com" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Salesforce Connected App 设置

对于 Client Credentials 流程（推荐方式）：

1. Salesforce Setup → App Manager → New Connected App。
2. 在 API (Enable OAuth Settings) 下：启用 Enable OAuth Settings 和 Enable Client Credentials Flow。
3. 保存后，等待约 5 分钟以完成同步。
4. 选择 Manage → Edit Policies → Client Credentials Flow → 设置 Run As 用户（API 调用将使用该用户的权限）。
5. 将 Connected App 中的 Consumer Key 和 Consumer Secret 复制到网关 BYOC 字段，分别作为 clientId 和 clientSecret。
6. 将 instanceUrl 设置为客户的 My Domain URL（Setup → My Domain）。

构建

npm install
npm run build

容器

该镜像在容器内的 0.0.0.0（MCP_HTTP_HOST）上监听，且默认使用 AUTH_MODE=gateway。在回环地址上发布端口，并传入 S2S 密钥。在网关模式下，Salesforce 凭据会作为请求头随每个请求传入；不会从环境中读取这些凭据。

docker build -t salesforce-mcp:dev .
docker run --rm \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  salesforce-mcp:dev
curl -s http://127.0.0.1:8080/health

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway、发布 127.0.0.1:8080:8080，并且不会注入 SALESFORCE_*：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍然需要 S2S 密钥，然后使用 SALESFORCE_*：

docker run --rm \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e SALESFORCE_AUTH_FLOW=client_credentials \
  -e SALESFORCE_CLIENT_ID=your-value \
  -e SALESFORCE_CLIENT_SECRET=your-value \
  -e SALESFORCE_INSTANCE_URL=https://yourorg.my.salesforce.com \
  -p 127.0.0.1:8080:8080 \
  salesforce-mcp:dev

已发布的镜像位于 ghcr.io/wyre-ai/salesforce-mcp，标签包括 :latest、:sha-<short_sha> 和 :v<version>。

许可证

Apache-2.0。