Auth0 Mcp Server

MCP（模型上下文协议） 是由 Anthropic 推出的一种开放协议，用于标准化大模型与外部工具、资源或远程服务的通信方式。

将 Claude、Cursor 或 Windsurf 连接到你的 Auth0 租户，即可创建应用、部署 Actions、调试日志和管理用户，全程无需访问控制台。

注意

Beta 软件声明：本软件目前处于 Beta 阶段，按“原样”提供，不提供任何保证。

• 功能、API 和特性可能随时更改，恕不另行通知
• 不建议用于生产环境或关键工作负载
• Beta 期间提供的支持有限
• 可通过 GitHub 问题跟踪器报告问题和反馈

使用本 Beta 软件即表示你知晓并接受这些条件。

Auth0 MCP 服务可与大模型和 AI Agent 集成，让你使用自然语言执行各种 Auth0 管理操作。例如，你只需让 Claude Desktop 执行 Auth0 管理操作：

• 创建新的 Auth0 应用并获取域名和客户端 ID

• 创建并部署新的 Auth0 Action，以生成 JWT 令牌

• 可以帮我检查 Auth0 日志中来自 IP 地址 192.108.92.3 的登录记录吗？

🚀 快速开始

前提条件：

• Node.js v18 或更高版本
• Claude Desktop 或其他任何 MCP 客户端
• 具备相应权限的 Auth0 账户

### 安装 Auth0 MCP Server

安装 Auth0 MCP Server，并将其配置为与你偏好的 MCP 客户端配合使用。--tools 参数用于指定可用的工具（如果未提供，则默认为 *）。

Claude Desktop（所有工具）

npx @auth0/auth0-mcp-server init

Claude Desktop（只读工具）

npx @auth0/auth0-mcp-server init --read-only

你也可以明确选择只读工具：

npx @auth0/auth0-mcp-server init --tools 'auth0_list_*,auth0_get_*'

Claude Code

为 Claude Code 初始化 Auth0 MCP 服务

npx @auth0/auth0-mcp-server init --client claude-code

系统会提示你选择配置范围：

• 用户 — 写入 ~/.claude.json，并在所有项目中可用。
• 项目 — 写入你指定的项目文件夹中的 .mcp.json，适合纳入版本控制并与你的团队共享。

Windsurf

npx @auth0/auth0-mcp-server init --client windsurf

Cursor

步骤 1：

步骤 2：

npx @auth0/auth0-mcp-server init --client cursor

Cursor（有限工具访问权限）

npx @auth0/auth0-mcp-server init --client cursor --tools 'auth0_list_applications,auth0_get_application'

VS Code

npx @auth0/auth0-mcp-server init --client vscode

你可以将 VS Code 配置为全局范围或工作区范围：

• 全局：在所有 VS Code 实例中可用
• 工作区：仅在特定项目／代码库中可用

命令会提示你选择偏好的范围，并自动配置相应的 mcp.json 文件。

VS Code（有限工具访问权限）

npx @auth0/auth0-mcp-server init --client vscode --tools 'auth0_list_*,auth0_get_*' --read-only

Gemini CLI

为 Gemini CLI 初始化 Gemini MCP 服务

npx @auth0/auth0-mcp-server init --client gemini

安装 Gemini Extension

gemini extensions install https://github.com/auth0/auth0-mcp-server

Codex CLI

使用 Auth0 进行一次身份验证：

npx @auth0/auth0-mcp-server init

然后将 Auth0 MCP 服务添加到 Codex：

codex mcp add auth0 --env DEBUG=auth0-mcp --env DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus -- npx -y @auth0/auth0-mcp-server run

你也可以直接将其添加到 ~/.codex/config.toml：

[mcp_servers.auth0]
command = "npx"
args = ["-y", "@auth0/auth0-mcp-server", "run"]

[mcp_servers.auth0.env]
DEBUG = "auth0-mcp"
DBUS_SESSION_BUS_ADDRESS = "unix:path=/run/user/1000/bus"

更新配置后重启 Codex。

其他 MCP 客户端

若要将 Auth0 MCP Server 与其他任何 MCP 客户端配合使用，你可以手动将此配置添加到客户端，然后重启以使更改生效：

{
  "mcpServers": {
    "auth0": {
      "command": "npx",
      "args": ["-y", "@auth0/auth0-mcp-server", "run"],
      "capabilities": ["tools"],
      "env": {
        "DEBUG": "auth0-mcp"
      }
    }
  }
}

你可以在 args 数组中添加 --tools '<pattern>'，以控制哪些工具可用。建议使用的模式请参见工具访问安全最佳实践。

使用 Auth0 授权

浏览器会自动打开，以启动 OAuth 2.0 设备授权流程。登录你的 Auth0 账户并授予请求的权限。

说明

凭据会安全地存储在系统钥匙串中。你也可以通过钥匙串管理工具验证凭据是否已存储。更多信息请参见身份验证。

验证集成

重启 MCP 客户端（Claude Desktop、Windsurf、Cursor 等），并让它协助你管理 Auth0 租户

为项目接入 Auth0

若要从头开始为项目接入 Auth0，请让 MCP 客户端为其完成接入（例如 Onboard my Next.js project with Auth0）。这会调用 auth0_onboarding 工具，创建一个针对你的框架配置的 Auth0 应用，并将凭据写入项目中的 .env 文件。该工具会在底层组合使用 auth0_create_application 和 auth0_save_credentials_to_file 工具完成此操作。接着，它会交由 auth0_get_quickstart_guide 处理，以解析你的回调 URL、更新应用，并返回适用于该框架的代码，用于集成 Auth0 SDK——通过单次引导式流程，帮你从尚未配置 Auth0 一步完成可用的集成。

🛠️ 支持的工具

Auth0 MCP Server 提供以下工具，供 Claude 与你的 Auth0 租户交互：

应用程序

工具	描述	使用示例
auth0_list_applications	列出 Auth0 租户中的所有应用程序，或按名称搜索	- Show me all my Auth0 applications - Find applications with 'api' in their name - What applications do I have in my Auth0 tenant?
auth0_get_application	获取特定 Auth0 应用程序的详细信息	- Show me details for the application called 'Customer Portal' - Get information about my application with client ID abc123 - What are the callback URLs for my 'Mobile App'?
auth0_create_application	创建新的 Auth0 应用程序	- Create a new single-page application called 'Analytics Dashboard' - Set up a new native mobile app called 'iOS Client' - Create a machine-to-machine application for our background service
auth0_update_application	更新现有的 Auth0 应用程序	- Update the callback URLs for my 'Web App' to include https://staging.example.com/callback - Change the logout URL for the 'Customer Portal' - Add development environment metadata to my 'Admin Dashboard' application
auth0_save_credentials_to_file	将应用程序凭据保存为环境变量，写入项目的 .env 文件（并将其添加到 .gitignore）	- Save my app's Auth0 credentials to a .env file in this project - Write the client ID and secret for 'Web App' to .env.local - Store these Auth0 credentials in my project's environment file

入门

工具	描述	使用示例
auth0_onboarding	使用 Auth0 为项目完成入门设置：创建针对指定框架配置的应用，并将凭据保存到 .env 文件	- 使用 Auth0 为我的 Next.js 项目完成入门设置 - 在此目录中为我的 React 应用设置 Auth0 - 使用 Auth0 启动我的 Express 应用
auth0_get_quickstart_guide	获取框架快速入门提示词，解析并更新回调 URL，并返回用于集成 Auth0 SDK 的代码	- 告诉我如何将 Auth0 SDK 添加到我的 Next.js 应用 - 完成我项目的 Auth0 集成 - 提供我的 React 应用的快速入门代码

资源服务器

工具	描述	使用示例
auth0_list_resource_servers	列出 Auth0 租户中的所有资源服务器（API）	- 显示我的 Auth0 租户中的所有 API - 列出我的资源服务器 - 我在 Auth0 中配置了哪些 API？
auth0_get_resource_server	获取指定 Auth0 资源服务器的详细信息	- 显示“User API”的详细信息 - “Payment API”定义了哪些作用域？ - 获取标识符为 https://api.example.com 的资源服务器信息"
auth0_create_resource_server	创建新的 Auth0 资源服务器（API）	- 创建一个名为“Inventory API”的新 API，并设置读写作用域 - 为我们的客户数据 API 设置资源服务器 - 创建标识符为 https://orders.example.com 的 API"
auth0_update_resource_server	更新现有的 Auth0 资源服务器	- 为“User API”添加“admin”作用域 - 将我的“Payment API”的令牌有效期更新为 1 小时 - 将我的 API 的签名算法改为 RS256

应用授权

工具	描述	使用示例
auth0_create_application_grant	创建客户端授权，允许 Auth0 应用使用指定的权限范围访问特定 API	- Grant my 'Backend Service' application access to the 'User API' - Create a client grant for my M2M app to call the payments API - Authorize my application to access the inventory API with read and write scopes

操作

工具	描述	使用示例
auth0_list_actions	列出 Auth0 租户中的所有操作	- Show me all my Auth0 actions - What actions do I have configured? - List the actions in my tenant
auth0_get_action	获取特定 Auth0 操作的详情	- Show me the code for my 'Enrich User Profile' action - Get details about my login flow action - What does my 'Add Custom Claims' action do?
auth0_create_action	创建新的 Auth0 操作	- Create an action that adds user roles to tokens - Set up an action to log failed login attempts - Create a post-login action that checks user location
auth0_update_action	更新现有的 Auth0 操作	- Update my 'Add Custom Claims' action to include department information - Modify the IP filtering logic in my security action - Fix the bug in my user enrichment action
auth0_deploy_action	部署 Auth0 操作	- Deploy my 'Add Custom Claims' action to production - Make my new security action live - Deploy the updated user enrichment action

日志

工具	描述	使用示例
auth0_list_logs	列出 Auth0 租户中的日志	- Show me recent login attempts - Find failed logins from the past 24 hours - Get authentication logs from yesterday - Show me successful logins for user [email protected]
auth0_get_log	根据 ID 获取特定日志条目	- Show me details for log entry abc123 - Get more information about this failed login attempt - What caused this authentication error?

表单

工具	描述	使用示例
auth0_list_forms	列出 Auth0 租户中的所有表单	- Show me all my Auth0 forms - What login forms do I have configured? - List the custom forms in my tenant
auth0_get_form	获取特定 Auth0 表单的详细信息	- Show me the details of my 'Corporate Login' form - What does my password reset form look like? - Get the configuration for my signup form
auth0_create_form	创建新的 Auth0 表单	- Create a new login form with our company branding - Set up a custom signup form that collects department information - Create a password reset form with our logo
auth0_update_form	更新现有的 Auth0 表单	- Update the colors on our login form to match our new brand guidelines - Add a privacy policy link to our signup form - Change the logo on our password reset form
auth0_publish_form	发布 Auth0 表单	- Publish my updated login form - Make the new signup form live - Deploy the password reset form to production

🔒 工具访问安全最佳实践

配置 Auth0 MCP 服务时，务必遵循安全最佳实践，根据具体需求限制工具访问权限。该服务提供灵活的配置选项，让你能够控制 AI 助手可以访问哪些工具。

启动服务时，可使用 --tools 和 --read-only 标志轻松限制工具访问：

# Enable only read-only operations
npx @auth0/auth0-mcp-server run --read-only

# Alternative way to enable only read-only operations
npx @auth0/auth0-mcp-server run --tools 'auth0_list_*,auth0_get_*'

# Limit to just application-related tools
npx @auth0/auth0-mcp-server run --tools 'auth0_*_application*'

# Limit to read-only application-related tools
# Note: --read-only takes priority when used with --tools
npx @auth0/auth0-mcp-server run --tools 'auth0_*_application*' --read-only

# Restrict to only log viewing capabilities
npx @auth0/auth0-mcp-server run --tools 'auth0_list_logs,auth0_get_log'

# Run the server with all tools enabled
npx @auth0/auth0-mcp-server run --tools '*'

重要

同时使用 --read-only 和 --tools 标志时，出于安全考虑，--read-only 标志优先级更高。这意味着，即使 --tools 模式匹配到非只读工具，也只能执行只读操作。这样，你就可以将 --read-only 标志作为安全防护措施。

对于无法传递 CLI 标志的环境（例如 MCP 捆绑包安装），也可以使用环境变量进行相同的控制：

变量	对应标志	示例
AUTH0_MCP_READ_ONLY	--read-only	AUTH0_MCP_READ_ONLY=true
AUTH0_MCP_TOOLS	--tools	AUTH0_MCP_TOOLS=auth0_list_*,auth0_get_*

同时提供 CLI 标志和环境变量时，CLI 标志优先级更高。

这种做法有几个重要优点：

1. 增强安全性：只开放所需的工具，可以缩小潜在攻击面，并防止对 Auth0 租户进行意外修改。

2. 提升性能：减少提供给 AI 助手的工具数量实际上有助于提升性能。当模型可以使用的工具很多时，它们会占用更多上下文窗口来判断应使用哪些工具。工具集更精简，响应就会更快、更贴合需求。

3. 基于资源的访问控制：你可以根据具体需求，为不同的 MCP 服务实例配置不同的工具集——开发环境可能需要完全访问权限，而生产环境则可以限制为只读操作。

4. 简化审计：工具数量有限时，更容易追踪通过 AI 助手执行了哪些操作。

对于大多数使用场景，建议从满足需求的最少工具集开始，仅在必要时添加更多工具。这遵循最小权限原则——一项基本的安全最佳实践。

🛡️ 凭据保护

该服务会自动在相关 MCP 工具响应中隐藏敏感字段（例如 client_secret、token 等），并将其替换为 [REDACTED]。这样可以防止机密泄露到 AI 助手日志或对话历史中。

如需在本地安全存储凭据，auth0_save_credentials_to_file 工具会将 Auth0 凭据作为环境变量写入用户指定的文件（例如 .env.local），并自动将该文件添加到 .gitignore 中。如果文件已存在，凭据会追加到文件中（保留现有内容）；否则会创建新文件。你可以手动调用此工具，也可以在创建应用后由 AI 助手自动提示你保存凭据。

🧪 安全扫描

我们建议定期扫描此服务以及你部署的其他兼容 MCP 的服务。可以使用社区工具来发现协议层面的风险和配置错误。

这些扫描工具有助于识别多类漏洞，包括：服务实现漏洞、工具定义和生命周期风险、交互和数据流弱点，以及配置或环境方面的缺漏。

可用的工具包括：

• mcpscan.ai
  基于 Web 的扫描工具，可检查在线 MCP 端点是否存在暴露的工具、架构约束缺漏及其他问题。

• mcp-scan
  命令行工具，可模拟攻击路径，并从客户端的角度评估服务行为。

这些工具不能替代完整审计，但可以提供有效的防护措施和早期预警。建议将其纳入定期安全审查流程。

如果发现漏洞，请遵循我们的负责任披露流程。

🕸️ 架构

Auth0 MCP Server 实现了 Model Context Protocol，使 Claude 能够：

1. 请求获取可用 Auth0 工具的列表
2. 使用参数调用特定工具
3. 接收来自 Auth0 Management API 的结构化响应

此服务负责身份验证、请求验证，以及与 Auth0 Management API 的安全通信。

说明

此服务以本地进程的形式运行，并连接到 Claude Desktop，从而实现安全通信，同时避免暴露你的 Auth0 凭据。

🔐 身份验证

Auth0 MCP Server 使用 Auth0 Management API，访问你的 Auth0 租户需要进行身份验证。

初始设置

对 MCP Server 进行身份验证：

npx @auth0/auth0-mcp-server init

这将启动设备授权流程，让你登录 Auth0 账户并选择要使用的租户。

说明

私有云租户不支持使用设备授权流程进行身份验证。 私有云用户应使用客户端凭据进行身份验证。请尽可能缩短令牌的有效期，以降低安全风险。了解详情

npx @auth0/auth0-mcp-server init --auth0-domain <auth0-domain> --auth0-client-id <auth0-client-id> --auth0-client-secret <auth0-client-secret>

重要

为客户端凭据 M2M 应用设置有限的范围：

支持的范围：

• read:clients
• create:clients
• update:clients
• read:resource_servers
• create:resource_servers
• update:resource_servers
• read:actions
• create:actions
• update:actions
• read:logs
• read:forms
• create:forms
• update:forms

遇到以下情况时，需要运行 `init` 命令：

• 首次设置 MCP Server
• 已退出之前的会话
• 想要切换到其他租户
• 令牌已过期

run 命令会在启动服务前自动检查令牌是否有效，并在需要进行身份验证时提供有用的错误提示。

说明

使用 MCP Server 会根据订阅计划消耗 Management API 的速率限制配额。更多信息请参阅速率限制政策。

提示

使用 --no-interaction 标志可跳过用户交互（按回车键）来打开浏览器的步骤。在 AI Agent 等特定环境中启动 MCP 服务时，这会很有用。

会话管理

查看当前认证会话的信息：

npx @auth0/auth0-mcp-server session

登出

为遵循安全最佳实践，会话结束后请始终使用登出命令：

npx @auth0/auth0-mcp-server logout

这样可以确保认证令牌从系统密钥链中正确移除。

认证流程

该服务使用 OAuth 2.0 设备授权流程，通过 Auth0 进行安全认证。您的凭据会安全地存储在系统密钥链中，绝不会以明文形式暴露。

🩺 故障排除

使用 Auth0 MCP Server 时若遇到问题，可通过多种故障排除选项来诊断并解决问题。

首先，查看所有可用命令和选项：

npx @auth0/auth0-mcp-server help

🚥 运行模式

🐞 调试模式

• 提供更详细的日志
• 设置环境变量以启用：export DEBUG=auth0-mcp

提示

调试模式尤其适用于排查连接或认证问题。

🔑 范围选择

该服务在初始化时会提供交互式范围选择界面：

• 交互式选择：使用方向键导航，并按空格键切换选项

• 不选择默认范围：默认情况下不选择任何范围，以确保最高安全性

• 支持 Glob 模式：使用模式快速选择多个相关范围：

  # Select all read scopes
  npx @auth0/auth0-mcp-server init --scopes 'read:*'
  
  # Select multiple scope patterns (comma-separated)
  npx @auth0/auth0-mcp-server init --scopes 'read:*,create:clients,update:actions'
  

说明

所选范围决定 MCP 服务可以对您的 Auth0 租户执行哪些操作。

⚙️ 配置

其他 MCP 客户端：

若要在其他 MCP 客户端中使用 Auth0 MCP Server，可将此配置添加到客户端，并重启客户端以使更改生效：

{
  "mcpServers": {
    "auth0": {
      "command": "npx",
      "args": ["-y", "@auth0/auth0-mcp-server", "run"],
      "capabilities": ["tools"],
      "env": {
        "DEBUG": "auth0-mcp"
      }
    }
  }
}

说明

如有需要，或在执行 npx init 命令时遇到意外错误，可手动更新。

🚨 常见问题

1. 认证失败

   • 确保您在 Auth0 租户中拥有正确的权限
   • 尝试使用 npx @auth0/auth0-mcp-server init 重新初始化

2. Claude Desktop 无法连接到服务

   • 安装后重启 Claude Desktop
   • 使用 ps aux | grep auth0-mcp 检查服务是否正在运行

3. API 错误或权限问题

   • 使用 export DEBUG=auth0-mcp 启用调试模式
   • 检查 Auth0 令牌状态：npx @auth0/auth0-mcp-server session
   • 使用指定范围重新初始化：npx @auth0/auth0-mcp-server init --scopes 'read:*,update:*,create:*'
   • 如果某项操作失败，您可能缺少所需范围

4. Auth0 配置无效错误

   • 通常是授权令牌缺失或已过期所致
   • 运行 npx @auth0/auth0-mcp-server session 检查令牌状态
   • 如果令牌已过期或缺失，运行 npx @auth0/auth0-mcp-server init 进行认证

提示

重启服务和 Claude Desktop 通常可以解决大多数连接问题。

📋 调试日志

启用调试模式以查看详细日志：

export DEBUG=auth0-mcp

获取 Claude Desktop 中详细的 MCP 客户端日志：

# Follow logs in real-time
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

如需进行高级故障排除，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector -e DEBUG='auth0-mcp' @auth0/auth0-mcp-server run

如需查看详细的 MCP 服务日志，请在调试模式下运行服务：

DEBUG=auth0-mcp npx @auth0/auth0-mcp-server run

👨‍💻 开发

从源代码构建

# Clone the repository
git clone https://github.com/auth0/auth0-mcp-server.git
cd auth0-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Initiate device auth flow
npx . init

# Configure your MCP Client (e.g. Claude Desktop) with MCP server path
npm run setup

开发脚本

# Run directly with TypeScript (no build needed)
npm run dev

# Run with debug logs enabled
npm run dev:debug

# Run with MCP inspector for debugging
npm run dev:inspect

# Run the compiled JavaScript version
npm run start

说明

此服务需要 Node.js v18 或更高版本。

🔒 安全

Auth0 MCP 服务将安全放在首位：

• 凭据存储在系统的安全密钥链中
• 不会以纯文本形式存储任何敏感信息
• 身份验证使用 OAuth 2.0 设备授权流程
• 默认不请求任何权限（作用域）
• 交互式作用域选择功能让你可以准确选择要授予的权限
• 支持 glob 模式，可快速选择相关作用域（例如，read:*）
• 不再需要时，可通过 logout 命令轻松移除令牌

重要

为遵循安全最佳实践，会话结束或切换租户时，请务必使用 npx @auth0/auth0-mcp-server logout。这可确保从系统密钥链中正确移除身份验证令牌。

注意

请务必检查身份验证过程中请求的权限，确保其符合你的安全要求。

匿名化分析数据披露

使用此 MCP 服务期间会收集匿名化数据点。这些数据包括 MCP 版本、操作系统、时间戳及其他无法识别你个人身份的技术信息。

Auth0 使用这些数据更好地了解此工具的使用情况，从而优先处理对用户最重要的功能、改进和修复。

如要选择退出此项数据收集，请将 AUTH0_MCP_ANALYTICS 环境变量设为 false。

💬 反馈与贡献

我们欢迎对此项目提出反馈并作出贡献！开始之前，请参阅：

• Auth0 的一般贡献指南
• Auth0 的行为准则

报告问题

如要提供反馈或报告 Bug，请在问题跟踪器中提交问题。

漏洞报告

请勿在 GitHub 公开问题跟踪器中报告安全漏洞。负责任披露计划详细说明了披露安全问题的流程。

📄 许可证

此项目采用 MIT 许可证。更多信息请参阅 LICENSE 文件。

Auth0 是什么？

Auth0 是一个易于实施且灵活的身份验证和授权平台。要了解详情，请查看 为什么选择 Auth0？