mcp-api

预览版 FusionAuth API MCP 服务（fusionauth-mcp-api）

FusionAuth API MCP 服务的预览版。 使用优秀的 github.com/harsha-iiiv/openapi-mcp-generator 构建。

⚠️ 不可用于生产环境！

使用此 MCP 服务需要向 MCP 客户端提供 FusionAuth API 密钥。请仅用于开发和测试实例。FusionAuth 不对敏感信息可能泄露承担责任。

前提条件

• 正在运行的 FusionAuth 实例
• Node.js

配置

首先，在 FusionAuth 实例中创建一个权限受限的 API 密钥。请参阅有关创建 API 密钥和为 API 密钥配置正确权限的文档。

接下来，配置 MCP 客户端以使用 FusionAuth API MCP 服务。

例如，要添加到 Claude Desktop，请编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，并加入下面的 fusionauth-mcp-api 键。

如果之前没有安装过 MCP 服务，配置文件应如下所示：

{
  "mcpServers": {
      "fusionauth-mcp-api": {
      "command": "npx",
      "args": [
        "@fusionauth/mcp-api"
      ],
      "env": {
        "API_KEY_APIKEYAUTH": "<your fusionauth api key>",
        "API_BASE_URL": "http://localhost:9011",
        "USE_TOOLS": "retrieve,search"
      }
    }
  }
}

上面的 USE_TOOLS 环境变量实际上会将可用工具限制为只读操作。你可以省略此变量以允许完全访问，但你需要使用能够处理约 200k 个 token 的模型。

请查阅 MCP 客户端的文档，了解如何将 MCP 服务添加到客户端。

提示词示例

• “你可以访问哪些工具？”应显示所有 FusionAuth API 工具
• “我的 FusionAuth 应用有多少个？”
• “我的 FusionAuth 实例中有多少个用户？”
• “添加一个邮箱地址为 [email protected]、密码为 'password' 的用户”（需要限制较少的工具）

限制工具

默认的 MCP 服务为 FusionAuth 的每个 API 端点都提供一个工具，超过 300 个！ 但是，这些工具、描述、请求和响应合计接近 200k 个 token，可能会超出许多 MCP 客户端的上下文窗口。

你可以通过设置上面所示的 USE_TOOLS 环境变量，限制此 MCP 服务提供哪些工具。

每个工具都按其前缀定义。默认前缀包括：

• create
• delete
• patch
• update
• retrieve
• search

此外，还有一个 other 工具类别，其中包含所有使用其他前缀的工具。all 工具类别包含所有工具，且为默认值。

例如，如果你不需要使用任何 delete 或 patch 方法，下面的设置可以将工具列表缩减 20%。

USE_TOOLS="create,update,retrieve,search,other"

如果只想允许只读操作，请使用以下配置：

USE_TOOLS="retrieve,search"

这也会将工具列表缩减 66%。

保护您的 MCP 服务

有三种不同的方法可以保护您的 MCP 服务。您应结合使用这些方法，在满足功能需求的同时，确保能够安全访问您的 FusionAuth 实例。按照粒度从粗到细排列如下：

• 指向正确的实例。此工具目前处于预览阶段，我们建议您仅将其指向本地开发实例。
• 启用正确类型的工具。除了减少上下文窗口用量，限制大模型可以发起的请求类型也能提升安全性。例如，如果您不启用 delete 工具集，就不必担心大模型为了“帮忙”而删除 FusionAuth 配置。
• 限制 API 密钥的权限。这比选择工具提供了更精细的控制。MCP 服务使用 API 密钥与 FusionAuth 通信。您可以选择适当的权限集，将该 API 密钥限制为只能操作租户、应用和用户。

故障排除

请确认您的 API 密钥具有 MCP 客户端正在执行的操作所需的正确权限。

请查看 MCP 客户端日志；日志位置因 MCP 客户端和平台而异。例如，在 macOS 上，Claude Desktop 的日志位于 $HOME/Library/Logs/Claude/mcp-server-fusionauth-api-server.log。请查阅客户端文档，了解确切位置。

使用 modelcontextprotocol 检查器来判断问题出在 MCP 服务还是 MCP 客户端：npx @modelcontextprotocol/inspector。如果要更改 USE_TOOLS 变量，您无法动态更改它，必须在命令行中传入。npx @modelcontextprotocol/inspector npx @fusionauth/mcp-api -e API_KEY_APIKEYAUTH=... -e USE_TOOLS=create

本地构建

您也可以在本地构建并运行。

git clone https://github.com/FusionAuth/fusionauth-mcp-api.git
cd fusionauth-mcp-api
cd packages/mcp-api
npm install
npm run build

# optional step to store config information in .env file
cp .env.example .env
# optionally edit .env to set API_BASE_URL and API_KEY_APIKEYAUTH

然后，按照上述说明配置 MCP 客户端，以使用 FusionAuth API MCP 服务。

例如，要将其添加到 Claude Desktop，请编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，并加入下方的 fusionauth-mcp-api 键。如果您尚未安装任何 MCP 服务，配置内容如下：

{
  "mcpServers": {
    "fusionauth-mcp-api": {
      "command": "npm",
      "args": [
        "run",
        "--silent",
        "--prefix",
        "<path to local git repo>/fusionauth-mcp-api/packages/mcp-api",
        "start"
      ],
      "env": {
        "API_KEY_APIKEYAUTH": "<your fusionauth api key>",
        "API_BASE_URL": "http://localhost:9011",
        "USE_TOOLS": "retrieve,search"
      }
    }
  }
}

如果已配置 .env 文件，可以省略上方的 env 部分。

发布

bin/updatemcp.sh git commit git tag git push origin main --tags npm publish --access public --workspace=packages/mcp-api

反馈

请在此仓库中提交功能请求和 Bug。

如果您想分享有趣的使用案例，或询问如何使用相关功能，请在 FusionAuth 论坛发帖。