MCP Oauth Password

______________________________________________________________________

状态：已发布 类别：mcp服务器 作者：阿纳尔多·德利西奥 published_npm:false npm_package:mcp-oauth密码 已发布目录：\[\] 生产url：空 最新活动：2026-01-26

mcp-oauth密码

MCP（模型上下文协议）服务器的简单基于密码的OAuth 2.1实现。 不需要第三方OAuth提供者 -只需要一个密码和PostgreSQL。

为什么？

大多数MCP OAuth实现都需要复杂的第三方提供商（GitHub、Keycloak、Auth0）。此套餐提供：

• ✅ 简单密码验证 -不需要GitHub/Google/Auth0
• ✅ 符合OAuth 2.1标准 -使用PKCE的授权码流
• ✅ 个人使用安全 -持久会话、安全Cookie、bcrypt
• ✅ 在Claude手机上工作 -测试和工作
• ✅ 自足 -只有Node.js+PostgreSQL

非常适合个人MCP服务器和自托管工具。

安全和生产准备

✅ 当前版本（0.2.x）： 适用于 个人/自托管 具有增强安全性的MCP服务器

生产路线图：

• v0.2.0版本 ✅ - 速率限制+审计日志记录
• v0.3.0 （即将推出）-令牌过期+刷新令牌
• v1.0.0 -生产就绪，支持多用户

安全功能（v0.2.0）：

• ✅ OAuth 2.1与PKCE
• ✅ Bcrypt密码哈希（10轮）
• ✅ 安全会话Cookie（仅httpOnly、安全、sameSite）
• ✅ PostgreSQL会话存储（持久）
• ✅ 短暂的身份验证码（10分钟，一次性）
• ✅ 重定向URI验证
• ✅ HTTPS在生产环境中的实施
• ✅ 新 速率限制（每15分钟5次登录尝试）
• ✅ 新 审核日志记录（跟踪所有身份验证事件）

尚未投入生产：

• ❌ 令牌过期+刷新令牌
• ❌ 多用户支持
• ❌ 尝试失败后帐户锁定

对于生产使用，请等待v1.0或自行添加令牌过期。

安装

npm install mcp-oauth-password

快速开始

import express from 'express';
import { setupOAuth, createAuthMiddleware } from 'mcp-oauth-password';

const app = express();

// 1. Setup OAuth endpoints
setupOAuth(app, {
  serverUrl: 'https://your-server.com',
  database: process.env.DATABASE_URL,
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  passwordHash: '$2b$10$...', // bcrypt hash of your password
  sessionSecret: 'random-secret-key',
  apiKey: 'your-api-key',
});

// 2. Configure EJS for login view
app.set('view engine', 'ejs');
app.set('views', './node_modules/mcp-oauth-password/views');

// 3. Protect your MCP endpoints
const authMiddleware = createAuthMiddleware({
  serverUrl: 'https://your-server.com',
  apiKey: 'your-api-key',
});

app.post('/mcp', authMiddleware, (req, res) => {
  // Your MCP handler
});

app.listen(3000);

配置

OAuthConfig

interface OAuthConfig {
  /** Server URL (e.g., 'https://your-server.com') */
  serverUrl: string;

  /** PostgreSQL connection string or Pool instance */
  database: string | Pool;

  /** Static OAuth client ID (pre-registered) */
  clientId: string;

  /** Static OAuth client secret (pre-registered) */
  clientSecret: string;

  /** Bcrypt hash of the login password */
  passwordHash: string;

  /** Session secret for cookie signing */
  sessionSecret: string;

  /** API key returned as access token */
  apiKey: string;

  /** Session cookie name (default: 'mcp_session') */
  sessionName?: string;

  /** Session max age in ms (default: 30 days) */
  sessionMaxAge?: number;

  /** Allowed redirect URI prefixes */
  allowedRedirectPrefixes?: string[];

  /** OAuth scopes supported */
  scopes?: string[];

  /** Custom login view path (optional) */
  loginViewPath?: string;
}

生成凭据

密码哈希（bcrypt）

npm install -g bcrypt-cli
bcrypt-cli hash "your-password" 10

或者在Node.js中：

import bcrypt from 'bcrypt';
const hash = await bcrypt.hash('your-password', 10);
console.log(hash); // Use this as passwordHash

客户端ID和密码

import { randomBytes } from 'crypto';

const clientId = `mcp-${randomBytes(8).toString('hex')}`;
const clientSecret = randomBytes(32).toString('base64url');
const sessionSecret = randomBytes(32).toString('hex');
const apiKey = randomBytes(32).toString('base64url');

数据库设置

该包会自动创建所需的表：

• authorization_codes -临时身份验证码（10分钟TTL）
• oauth_clients -已注册OAuth客户端
• session -持续会话
• auth_logs -安全监控审计日志 （v0.2.0+）

只需提供一个PostgreSQL连接字符串。

v0.2.0中的新功能

速率限制

自动速率限制可防止暴力攻击：

• 登录： 每15分钟5次尝试
• 令牌： 每15分钟10次尝试
• 授权： 每15分钟20次尝试

速率限制会自动应用。您可以自定义它们：

import { setupOAuth, loginRateLimiter } from 'mcp-oauth-password';
import rateLimit from 'express-rate-limit';

// Use default rate limiting
setupOAuth(app, config);

// OR customize the login rate limiter
const customLimiter = rateLimit({
  windowMs: 10 * 60 * 1000, // 10 minutes
  max: 3, // 3 attempts
});

app.post('/login', customLimiter, ...);

审计日志

所有身份验证事件都会自动记录到 auth_logs 表：

SELECT * FROM auth_logs
WHERE event IN ('login_success', 'login_failure', 'token_exchange')
ORDER BY created_at DESC
LIMIT 100;

记录的事件：

• login_success / login_failure -密码登录尝试
• token_exchange / token_failure -OAuth令牌交换
• authorize_request -授权请求
• client_registration -新的OAuth客户端注册

每个日志包括：IP地址、用户代理、客户端ID、成功/失败、错误消息和时间戳。

Claude移动配置

添加到您的 .mcp.json:

{
  "mcpServers": {
    "your-server": {
      "type": "http",
      "url": "https://your-server.com/mcp",
      "oauth": {
        "clientId": "your-client-id",
        "clientSecret": "your-client-secret"
      }
    }
  }
}

API 参考

setupOAuth(app, config)

在Express应用程序上设置OAuth 2.1端点。

退货： { pool, sessionMiddleware }

创建的端点：

• GET /.well-known/oauth-protected-resource -RFC 9728元数据
• GET /.well-known/oauth-authorization-server -RFC 8414元数据
• GET /oauth/authorize -授权端点
• POST /oauth/token -令牌交换端点
• POST /login -密码登录处理程序
• POST /oauth/register -RFC 7591动态客户端注册

createAuthMiddleware(config)

创建Express中间件，通过Bearer令牌身份验证保护端点。

用途：

const authMiddleware = createAuthMiddleware(config);
app.post('/mcp', authMiddleware, handler);

自定义登录视图

创建自己的 login.ejs 并指出：

setupOAuth(app, {
  // ...
  loginViewPath: './views/custom-login.ejs'
});

app.set('view engine', 'ejs');
app.set('views', './views');

登录视图接收：

• error -错误信息（如有）
• originalUrl -登录后重定向的URL

环境变量示例

SERVER_URL=https://your-server.com
DATABASE_URL=postgresql://user:pass@localhost/dbname
OAUTH_CLIENT_ID=mcp-a8ff0614d0153f07
OAUTH_CLIENT_SECRET=cqlJlRhOpGE3n5ZOeW_PYERAY75-5lDqNoDMr3v1D7Y
OAUTH_PASSWORD_HASH=$2b$10$N9qo8uLOickgx2ZMRZoMye...
SESSION_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
API_KEY=your-api-key-here

完整示例

看 /example 完整的MCP服务器实现目录。

安全特性

• ✅ OAuth 2.1与PKCE（代码交换证明密钥）
• ✅ Bcrypt密码哈希
• ✅ 安全会话Cookie（仅httpOnly、安全、sameSite）
• ✅ PostgreSQL会话存储（重启后仍能继续）
• ✅ 授权码过期（10分钟）
• ✅ 动态客户端注册（RFC 7591）
• ✅ 承载令牌身份验证

与备选方案的比较

许可证

麻省理工学院

作者

阿纳尔多·德利西奥

贡献

欢迎在https://github.com/arnaldo-delisio/mcp-oauth-password