Fastly MCP Server

Fastly MCP 服务

Fastly MCP 服务让 MCP 客户端能够使用 Fastly API。

将它连接到 Claude Desktop、Claude Code、Gemini CLI、Opencode、Qwen Code、Cline 或 Swival 等助手，并提供 Fastly API 令牌。 然后，助手可以：

• 查找服务并检查域名和 TLS 设置。
• 查看流量和使用情况。
• 管理字典和 ACL。
• 按照你的要求清除内容并更改配置。

本项目正在积极开发中，并获得 Fastly 开源支持 Tier 1。 支持政策请参阅 Fastly 的开源文档。

欢迎在 Fastly 开发者工具社区论坛提出问题和反馈。

目录

• 工作原理
• 要求
• 安装
• 通过 HTTP 运行
• 为多个用户运行远程服务
• 有效使用服务
• 密钥加密
• 故障排除
• 本地开发
• 安全
• 许可证

工作原理

大多数 MCP 服务会为每种操作提供一个工具。 由于 Fastly 的 API 规模庞大，本服务使用较少的一组工具，供助手配合使用。

1. 首先使用 search，按关键字、方法名称、API 类或 HTTP 路径查找 API 方法。

2. 然后使用 inspect 获取方法文档，包括其参数、返回类型和示例。

3. 了解详细信息后，使用 execute 运行一段简短的 JavaScript 代码片段；其中的 Fastly 客户端已设置好你的 API 令牌。

这样既能让工具列表保持精简，又能涵盖随附 Fastly 客户端文档中记录的所有方法。

要求

运行环境

安装 Bun 或 Node.js 24.12.0 及更高版本即可；运行本服务不需要同时安装两者。 远程模式推荐使用 Node.js，详见远程模式。

示例使用 bunx，无需全局安装即可下载并运行软件包。 使用 Node.js 时，请改用 npx。

请使用完整的软件包名称和命令名称，以免调用 PATH 中无关的 mcp 命令：

• 使用 bunx： bunx -p @fastly/mcp fastly-mcp
• 使用 npx： npx -p @fastly/mcp fastly-mcp
• 明确使用 Bun： bunx --bun -p @fastly/mcp fastly-mcp

--bun 选项会使用 Bun 运行软件包，而不是遵循其 Node.js shebang。

Fastly API 令牌

你还需要一个 Fastly API 令牌。 日常使用时，请创建权限范围尽可能小、又能满足预期助手工作需求的令牌：

• 调查和报告时，先使用只读令牌。
• 只有在确实需要助手进行更改时，才使用具有写入权限的令牌。

请将令牌保存在 MCP 客户端配置或 shell 环境中，并命名为 FASTLY_API_TOKEN。

不要将生产环境令牌粘贴到提示词中，也不要将其提交到代码仓库。

安装

选择你的客户端：

Codex · Claude Code · Claude Desktop · Gemini CLI · Opencode · Qwen Code · Cline · Swival

大多数 MCP 客户端都接受用于描述如何启动服务的 JSON 配置块。 例如，以下配置使用 bunx 运行服务，并通过环境传递 API 令牌：

{
  "mcpServers": {
    "fastly": {
      "command": "bunx",
      "args": ["-p", "@fastly/mcp", "fastly-mcp"],
      "env": {
        "FASTLY_API_TOKEN": "your-token-here"
      }
    }
  }
}

如果你已在启动 MCP 客户端的 shell 中导出 FASTLY_API_TOKEN，通常可以省略 env 块（不过，某些 Agent 可能仍然需要它）。

对于桌面应用，将令牌保存在客户端配置中通常更简单；对于终端工具，使用 shell 环境变量通常更简洁。

Codex

本地服务可使用任一运行时。 内置插件通过 bunx 启动：

• 仅使用 Node.js 的设置： 使用 npx 作为 MCP 启动命令，并传入相同参数。
• 仅使用 Bun 的设置： 在启动参数中的 -p 前添加 --bun。

确保所选启动器可通过 Codex 的 PATH 找到。

将仓库添加为插件市场，然后安装插件：

codex plugin marketplace add https://github.com/fastly/mcp
codex plugin add fastly-mcp@fastly-local

add 命令会安装并启用插件。

在启动 Codex 的环境中设置 FASTLY_API_TOKEN，然后重启 Codex，以便本地服务接收到该变量。

插件通过 stdio 运行，并启用了密钥加密；它不需要 OAuth 或托管的 MCP 端点。

检查插件是否已安装并启用：

codex plugin list --marketplace fastly-local

Claude Code

通过 bunx 运行服务：

claude mcp add fastly -- bunx -p @fastly/mcp fastly-mcp

然后确保 FASTLY_API_TOKEN 在启动 Claude Code 的环境中可用，或者通过常规的 Claude Code MCP 设置配置令牌。

Claude Desktop

将上面的通用 JSON 配置块添加到 Claude Desktop 的配置文件中。

• 在 macOS 上，文件通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json。
• 在 Windows 上，文件通常位于 %APPDATA%\Claude\claude_desktop_config.json。
• 在 Linux 上，文件通常位于 ~/.config/Claude/claude_desktop_config.json。

修改文件后，重启 Claude Desktop。

Gemini CLI

将通用 JSON 配置块添加到 ~/.gemini/settings.json。

如果从已导出 FASTLY_API_TOKEN 的 Shell 启动 Gemini CLI，可以不在 JSON 中配置令牌。

Opencode

Opencode 使用略有不同的配置结构。

将以下内容放入项目中的 opencode.json，或放入 ~/.config/opencode/opencode.json 以配置全局服务：

{
  "mcp": {
    "fastly": {
      "type": "local",
      "command": ["bunx", "-p", "@fastly/mcp", "fastly-mcp"],
      "environment": {
        "FASTLY_API_TOKEN": "your-token-here"
      }
    }
  }
}

Qwen Code

将通用 JSON 配置块添加到 ~/.qwen/settings.json，或添加到特定项目中的 .qwen/settings.json。

Cline

打开 Cline MCP 设置，选择全局或项目 MCP 配置，然后粘贴通用 JSON 配置块。

Swival

将以下内容添加到项目中的 swival.toml：

[mcp_servers.fastly]
command = "bunx"
args = ["-p", "@fastly/mcp", "fastly-mcp"]
env = { FASTLY_API_TOKEN = "your-token-here" }

如果 FASTLY_API_TOKEN 已在 Swival 运行的环境中设置，则 env 行可省略。

Swival 也可以从 .swival/mcp.json 读取通用 JSON 配置块。

通过 HTTP 运行

默认情况下，服务通过 stdio 使用 MCP 通信，这是所有桌面和命令行客户端所需的方式。

若要让受信任的客户端共用一个 Fastly API 令牌，请以 HTTP 模式启动服务：

bunx -p @fastly/mcp fastly-mcp --transport http

该服务会监听 http://127.0.0.1:8231/mcp。默认仅绑定环回地址，且不进行身份验证。

然后使用服务的 URL 配置客户端：

{
  "mcpServers": {
    "fastly": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8231/mcp"
    }
  }
}

具体配置结构因客户端而异；请查阅客户端文档，了解 streamable-http 条目的格式。

请求之间不会保留任何状态，因此服务可部署在负载均衡器后，无需配置会话粘性。

在环回地址上使用 Authorization: Bearer

即使绑定到环回地址，也可以设置 FASTLY_MCP_HTTP_AUTH_TOKEN。

这样做不会带来安全风险，并且可以让配置以后轻松迁移到非环回部署。

使用 --help 查看完整的标志列表

上文介绍的所有标志都会显示在 bunx -p @fastly/mcp fastly-mcp --help 中。

为多个用户运行远程服务

如果每个调用方都应提供自己的 Fastly API 令牌，请使用 --remote-http。

远程 HTTP 部署指南介绍了凭据、客户端配置、HTTPS 代理、Docker、systemd、容量规划、日志记录和部署测试。

妥善使用服务

Fastly API 令牌可能会暴露真实的生产配置，而具有写入权限的令牌还可以更改这些配置。

服务不会猜测你的意图，因此最安全的工作流是明确说明助手是否可以进行任何更改。

只读操作

进行只读操作时，请直接说明。

例如，可以要求助手列出服务、查找某个服务的活动版本、汇总后端、检查 TLS 状态、检查日志端点，或报告近期流量，并明确要求不要进行任何更改。

进行更改

1. 首先说明助手应操作的服务、域名、版本、字典、ACL 或后端。

2. 在进行更改之前，要求它展示计划调用的方法。

如果更改会影响服务配置，通常最好先克隆一个服务版本，编辑克隆版本，向你展示差异或摘要，并且只在你批准后激活。

提示词示例

好的初始提示词如下：

列出我的 Fastly 服务，并显示每个服务的活动版本。不要进行更改。

找出为 www.example.com 提供服务的服务，并总结其域名、后端和运行状况检查。

检查用于清除单个 URL 的 API 方法，然后在执行前向我展示你将进行的确切调用。

克隆服务 ABC123 的活动版本，添加一个名为 origin-api 的后端，然后在激活前停止。

如果回答范围太广，请让助手先在代码中缩小结果范围，再返回结果。

有针对性的调用更易于审查，也不容易泄露无关信息。

Next-Gen WAF 调查

该服务提供只读的 NGWAF 方法，涵盖：

• 账户和工作区规则、信号与列表。
• 工作区设置和主要攻击。
• 事件列表和详情。
• 已存储请求的搜索和详情。
• 工作区时间序列。

Log Explorer 和 Insights

该服务提供只读的 Log Explorer & Insights 方法，涵盖：

• 请求日志搜索，可按状态、路径、响应时间、POP、设备或机器人缩小范围。
• 现成的排名，例如请求量最多或最慢的 URL。
• 自定义分组指标，例如每个 POP 的 p95 响应时间。

服务需要启用 Log Explorer & Insights 产品。

Fastly 会对这些数据进行采样，并保留七天。 因此，这些方法回答的是“缓慢请求看起来是什么样”，而不是“有多少个请求”。 需要精确计数时，请请求统计数据。

可观测性时间序列

该服务提供只读的时间序列方法，涵盖两类数据：

• 单个服务的请求日志，按秒、分钟、小时或天分桶。
• 整个账户的可持续性数据，例如带宽和 CPU 时间，按天或月统计。

请求日志序列需要启用 Log Explorer & Insights 产品。 这些数据来自相同的采样数据，因此是估算值，而非总计。

大型结果

只要结果能装进单个响应，就会完整返回，无论其中包含多少条记录：例如，包含数百名用户的列表也会完整返回。

无法装进单个响应的大型结果也不会被丢弃。 该服务会将完整结果写入 JSON 文件，并在响应的 resultFile 中附上文件路径，同时在 result 中提供简短预览。

如果你需要所有记录，请让助手读取该文件，而不要重新运行查询。

存储和限制

• **位置：**文件写入系统临时目录下的 fastly-mcp-results，每个文件保存一个结果，只有运行该服务的账户可以读取。

• **大小：**单个文件最多可容纳 4 MB；更大的结果会在响应中说明，并要求助手减少返回内容。 单次 Fastly API 调用可交给代码处理的数据也有相同的上限：更大的响应会使该调用失败，并提示进行分页或筛选，而不会在内容缺失的情况下悄然返回部分数据。

• **保留期限：**保留最新的二十个文件，每个文件都会在六小时后删除，无论此后服务是否繁忙。

• **配置：**使用 --result-dir <path> 将文件存放到其他位置，或使用 --result-dir off 关闭此功能，并让大型结果只作说明而不进行存储。

启用密钥加密后，密钥会在完整结果存储或裁剪为预览之前加密。 读取文件无法揭示响应原本会隐藏的值；即使预览恰好截断在令牌中间，也同样无法揭示。

远程服务从不写入结果文件，因为调用方无法读取这些文件。

密钥加密

Fastly API 响应可能包含凭据、密钥或其他敏感值。 在本地模式下，默认情况下，服务会将 Fastly 返回的 API 输出原样返回给 MCP 客户端。

远程模式始终会使用根据调用方令牌派生的密钥加密可识别的密钥，详见远程 HTTP 指南。

加密的工作方式

如果你希望在工具输出到达模型之前增加一层保护，请启用密钥加密。

启用加密后，每个可识别的令牌都会替换为类似 {ENCRYPTED:...} 的加密值，然后再发送给助手。 相同的令牌始终会得到相同的加密值，因此助手可以在后续调用中引用它。

当助手将加密值发回时，服务会在工具运行前对其解密。 如果该值被修改、截短，或使用不同的密钥生成，服务会返回错误，而不会猜测其原值。

如果无法安全地加密某个结果，整个结果都会被拦截。 当结果包含长度超过 512 个字符的令牌，或看起来已经是加密值的文本时，就会发生这种情况。

启用加密

若要在使用 bunx 的 MCP 配置中启用加密，请在二进制名称后添加 --encrypt-secrets：

{
  "mcpServers": {
    "fastly": {
      "command": "bunx",
      "args": ["-p", "@fastly/mcp", "fastly-mcp", "--encrypt-secrets"],
      "env": {
        "FASTLY_API_TOKEN": "your-token-here"
      }
    }
  }
}

你也可以通过环境变量启用：

{
  "mcpServers": {
    "fastly": {
      "command": "bunx",
      "args": ["-p", "@fastly/mcp", "fastly-mcp"],
      "env": {
        "FASTLY_API_TOKEN": "your-token-here",
        "FASTLY_MCP_ENCRYPT_SECRETS": "true"
      }
    }
  }
}

密钥与限制

对于本地加密，每次服务启动时都会生成一个新密钥，因此重启后，加密值将无法继续使用。

将 FASTLY_MCP_ENCRYPT_KEY 设置为恰好 32 个十六进制字符（即 16 字节密钥），可确保重启后使用相同的密钥，从而继续使用之前的加密值。

如果需要使用单独的 tweak 值进行域分离，也可以设置 FASTLY_MCP_ENCRYPT_TWEAK。 加密值只能与生成它时使用的 tweak 配合使用。

密钥加密是一项安全功能，并非完整的数据分类系统。 它只会加密符合已知令牌模式的值。

你仍应使用权限最小化的 Fastly 令牌，并避免要求助手检索机密，除非任务确有需要。

故障排除

API 调用失败

对于本地服务，如果 Fastly API 调用失败，请检查 MCP 服务所处的环境中是否设置了 FASTLY_API_TOKEN。

即使没有令牌，搜索和检查功能仍可使用，因为它们依赖内置文档；但实际 API 调用需要令牌。

调用失败时会报告 API 返回的信息，因此答案通常就在工具输出中：

{
  "error": "HTTP 401 Unauthorized",
  "status": 401,
  "body": "{\"msg\":\"Provided credentials are missing or invalid\"}",
  "hint": "Fastly rejected the API token. Check that FASTLY_API_TOKEN is current and has not been revoked."
}

401 或 403 错误中的提示会区分需要采取不同修复措施的三种情况：

• 没有令牌传到服务。
• Fastly 拒绝了收到的令牌。
• 令牌有效，但无权执行该操作。

这些字段在 execute 中也可用，因此代码片段可以捕获错误，并自行读取 e.status 或 e.body。

找不到方法

如果助手找不到合适的方法，请让它使用更宽泛的搜索词，例如 service、domain、backend、purge、tls、logging、dictionary、acl、vcl、stats，或 Fastly API 文档中的 HTTP 路径片段。

结果意外为空

如果结果意外为空，请让助手先返回原始 API 响应。

Fastly 客户端方法会直接返回值，而不会将值放在 .result 包装对象中。

返回预览而非完整数据

如果响应中包含预览而非数据，请在同一响应中查找 resultFile 路径：由于完整结果无法放入单个响应，因此已写入该路径。

让助手读取该文件，或在其运行的 JavaScript 代码中进行筛选、分页或字段选择。

如果缺少 resultFile，则表示结果文件已被禁用（--result-dir off），或服务无法写入结果文件；hint 字段会说明具体原因。

执行超时

由于每次 execute 调用的时限为 30 秒，如果发生超时，请将工作拆分为更小的调用。

本地开发

运行服务

服务入口点是 src/index.js。 Bun 是主要的开发运行时：

bun run src/index.js

运行检查

主要检查包括：

bun test
bun run lint

运行测试需要同时安装 Bun 和 Node。

已知的 Bun 1.3.11 错误被标记为预期失败，以便及时发现未来版本中的修复。

更新 API 文档

docs/ 中的 API 文档来自 Fastly JavaScript 客户端。 服务会在启动时使用这些文档构建搜索索引。

package.json 将该客户端固定为精确版本，以确保文档始终描述实际运行的代码。

使用以下命令重新生成：

bun run update-docs

不传入参数时，脚本会获取与固定版本匹配的 release/v<version> 标签。

传入分支或标签即可获取其他内容，例如升级客户端时。 升级时需同时更新 package.json、package-lock.json 和 bun.lock 中的固定版本。

安全

请按照 SECURITY.md 中的说明，通过 Fastly 的安全问题报告流程报告安全问题。

许可证

MIT。详情请参阅 LICENSE。