MCP Auth Wrapper

mcp身份验证包装器

转向任何本地 MCP服务器 将每个用户的凭据转换为多租户托管的远程MCP。

将AI代理与工具连接可以帮助您和您的团队提高工作效率。 MCP服务器 是一种很好的方法，但其中许多仅在本地运行，并且需要每个用户设置（如API密钥），这对非技术用户来说可能很困难。如果你想让你的整个团队都使用一个，每个人都有自己的证书，该怎么办？

mcp-auth-wrapper允许您做到这一点：它为具有身份验证和配置的多个用户托管任何mcp服务器。您的团队可以通过现有的身份提供者（Google Workspace、Microsoft Entra ID、Okta、Auth0、Keycloak等）登录，在简单的表单界面中提供每个用户的配置，mcp-auth-wrapper将自动为每个用户启动mcp。

mcp-auth-wrapper可与Claude.ai、Claude Code和支持远程服务器的任何其他mcp客户端配合使用。

用法

集 MCP_AUTH_WRAPPER_CONFIG 转到JSON配置对象并运行：

MCP_AUTH_WRAPPER_CONFIG='{
  "command": ["npx", "-y", "airtable-mcp-server"],
  "auth": {"issuer": "https://auth.example.com"}
}' npx -y mcp-auth-wrapper

这将在localhost:3000上启动HTTP MCP服务器。当用户连接时，他们将被重定向到您的登录提供商。登录后，如果您配置了每个用户的环境变量（如API键），他们将看到一个表单来输入它们。然后，它们连接到自己的MCP服务器进程。

Other configuration methods

env-var也可以指向文件路径：

MCP_AUTH_WRAPPER_CONFIG=/path/to/config.json npx -y mcp-auth-wrapper

或创建 mcp-auth-wrapper.config.json 在工作目录中，它会被自动拾取：

npx -y mcp-auth-wrapper

Running with Docker

docker run -e 'MCP_AUTH_WRAPPER_CONFIG={"command":["npx","-y","airtable-mcp-server"],"auth":{"issuer":"https://auth.example.com"}}' -p 3000:3000 ghcr.io/domdomegg/mcp-auth-wrapper

Running on Kubernetes

Docker镜像以非root身份运行 node 用户（uid 1000）。如果您将PersistentVolumeClaim用于SQLite存储，默认情况下卷装载将由root拥有，因此容器将无法写入。添加 fsGroup: 1000 转到pod的安全上下文以修复此问题：

spec:
  securityContext:
    fsGroup: 1000
  containers:
    - name: mcp-auth-wrapper
      image: ghcr.io/domdomegg/mcp-auth-wrapper
      volumeMounts:
        - name: data
          mountPath: /data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: mcp-auth-wrapper-data

配置

仅 command 和 auth.issuer 是必需的。其他一切都有合理的违约。

完整示例：

{
  "command": ["npx", "-y", "airtable-mcp-server"],
  "auth": {
    "issuer": "https://keycloak.example.com/realms/myrealm",
    "clientId": "my-wrapper",
    "clientSecret": "...",
    "scopes": ["openid", "profile"],
    "userClaim": "preferred_username"
  },
  "envBase": {"NODE_ENV": "production"},
  "envPerUser": [
    {"name": "AIRTABLE_API_KEY", "label": "Airtable API Key", "secret": true}
  ],
  "storage": "/data/mcp.sqlite",
  "port": 3000,
  "host": "0.0.0.0",
  "issuerUrl": "https://mcp.example.com",
  "secret": "a-fixed-signing-key"
}

用户可以随时通过 重新配置 自动添加到MCP服务器的工具列表中的工具。

Advanced: scaling and persistence

所有身份验证状态（令牌、会话、正在进行的登录）都是无状态的——令牌是自包含的加密blob，每个请求都会得到一个新的传输。除了用户参数（in storage)以及进程池（每个用户一个子进程）。

要在重新启动后继续运行，请设置 secret 将用户参数设置为固定值，并使用SQLite文件或内联存储。

要在负载平衡器后运行多个实例，请设置 secret 在实例和点之间达到相同的值 storage 在共享SQLite文件中（或使用内联存储）。如果用户点击不同的实例，它只会生成一个新的子流程——这对无状态MCP是透明的。

登录提供者示例

Google Workspace

{
  "command": ["npx", "-y", "some-mcp-server"],
  "auth": {
    "issuer": "https://accounts.google.com",
    "clientId": "...",
    "clientSecret": "..."
  },
  "envPerUser": [{"name": "API_KEY", "label": "API Key", "secret": true}]
}

在中创建OAuth 2.0凭据 谷歌云控制台。选择“Web应用程序”，添加 https:///callback 作为授权的重定向URI。要限制对组织的访问，请将OAuth同意屏幕配置为“内部”。

Microsoft Entra ID

{
  "command": ["npx", "-y", "some-mcp-server"],
  "auth": {
    "issuer": "https://login.microsoftonline.com//v2.0",
    "clientId": "...",
    "clientSecret": "..."
  },
  "envPerUser": [{"name": "API_KEY", "label": "API Key", "secret": true}]
}

在 Azure门户.添加 https:///callback 作为“Web”下的重定向URI。在“证书和机密”下创建客户端机密。替换 `` 使用您的目录（租户）ID。

Okta

{
  "command": ["npx", "-y", "some-mcp-server"],
  "auth": {
    "issuer": "https://your-org.okta.com",
    "clientId": "...",
    "clientSecret": "..."
  },
  "envPerUser": [{"name": "API_KEY", "label": "API Key", "secret": true}]
}

在Okta中创建Web应用程序。将登录重定向URI设置为 https:///callback。发行人URL是您的Okta组织URL（或自定义授权服务器URL，如果您使用的话）。

Keycloak

{
  "command": ["npx", "-y", "some-mcp-server"],
  "auth": {
    "issuer": "https://keycloak.example.com/realms/myrealm",
    "clientSecret": "..."
  },
  "envPerUser": [{"name": "API_KEY", "label": "API Key", "secret": true}]
}

使用客户端ID在Keycloak领域中创建OpenID Connect客户端 mcp-auth-wrapper （或设置 auth.clientId 匹配）。将重定向URI设置为 https:///callback。用户由以下人员标识 sub 默认情况下为（Keycloak用户ID）。集 auth.userClaim 到 preferred_username 改为按用户名匹配。

Auth0

{
  "command": ["npx", "-y", "some-mcp-server"],
  "auth": {
    "issuer": "https://your-tenant.auth0.com",
    "clientId": "...",
    "clientSecret": "..."
  },
  "envPerUser": [{"name": "API_KEY", "label": "API Key", "secret": true}]
}

在Auth0中创建常规Web应用程序。添加 https:///callback 作为允许的回调URL。设置 auth.clientId 到Auth0应用程序的客户端ID sub Auth0中的声明通常以连接类型作为前缀（例如。 auth0|abc123).

Authentik

{
  "command": ["npx", "-y", "some-mcp-server"],
  "auth": {
    "issuer": "https://authentik.example.com/application/o/myapp/",
    "clientSecret": "...",
    "userClaim": "preferred_username"
  },
  "envPerUser": [{"name": "API_KEY", "label": "API Key", "secret": true}]
}

使用客户端ID在Authentik中创建OAuth2/OpenID提供程序 mcp-auth-wrapper （或设置 auth.clientId 匹配）。将重定向URI设置为 https:///callback.

Home Assistant (via hass-oidc-provider)

Home Assistant本身不支持OpenID Connect。使用 hass oidc提供商 为了弥合差距，它与Home Assistant一起运行，并添加了缺失的部分。

{
  "command": ["npx", "-y", "some-mcp-server"],
  "auth": {
    "issuer": "https://hass-oidc-provider.example.com"
  },
  "envPerUser": [{"name": "API_KEY", "label": "API Key", "secret": true}]
}

点 auth.issuer 在您的hass-oidc提供商实例上（而不是直接在Home Assistant上）。这 sub claims是家庭助理用户ID。否 clientId 或 clientSecret 需要。

其他示例

Inline users (no self-registration)

默认情况下，用户在首次登录时通过表单输入自己的凭据（例如API密钥），然后可以通过重新配置工具更新这些凭据。如果你更愿意预先硬编码所有用户，请使用内联 storage 对象：

{
  "command": ["npx", "-y", "some-mcp-server"],
  "auth": {
    "issuer": "https://auth.example.com",
    "clientSecret": "..."
  },
  "storage": {
    "adam": {"API_KEY": "patXXX_adam"},
    "bob": {"API_KEY": "patXXX_bob"}
  }
}

用户通过以下方式匹配 auth.userClaim （默认值： sub)从登录令牌中。内联存储是只读的，用户无法更新自己的凭据。

贡献

GitHub上欢迎拉取请求！开始：

1. 安装Git和Node.js
2. 克隆仓库
3. 安装依赖项 npm install
4. 跑 npm run test 运行测试
5. 建立 npm run build

发布

版本遵循 语义版本规范.

要发布：

1. 使用 npm version 升级版本
2. 跑 git push --follow-tags 使用标签推送
3. 等待GitHub Actions发布到NPM注册表和GHCR（Docker）。