mcp-credentials-server

v1.1.0

Published

3 months ago

MCP Server for AI Agent credential management with 2FA support

0High
0Medium
0Low

hsuehic2023

mcp server credentials ai-agent 2fa authentication linkedin social-media

MCP Credentials Server

🔐 Secure Credential Management for AI Agents via Model Context Protocol

🚀 Quick Start for End Users

Installation

# Install the package globally
npm install -g mcp-credentials-server

# Or clone and build from source
git clone https://github.com/hsuehic/mcp-credentials-server.git
cd mcp-credentials-server
npm install
npm run build

Cursor Configuration

Open Cursor Settings (Cmd+, on Mac, Ctrl+, on Windows/Linux)
Search for "MCP" in settings
Add the following to your MCP server configuration:

⚡ Option A: Zero Configuration (Simplest)

{
  "mcpServers": {
    "mcp-credentials-server": {
      "command": "mcp-credentials-server"
    }
  }
}

✨ Features:

🔐 Automatically generates and saves encryption key
🚀 Production-optimized defaults (debug off)
📁 Auto-creates ~/.mcp-credentials/ storage
🔑 Encryption key saved to ~/.mcp-credentials/.encryption-key
🛡️ Secure file permissions (user-only access)

🚀 Option B: Global Installation (Manual Key)

{
  "mcpServers": {
    "mcp-credentials-server": {
      "command": "mcp-credentials-server",
      "env": {
        "MCP_ENCRYPTION_KEY": "your-32-character-encryption-key-here",
        "NODE_ENV": "production"
      }
    }
  }
}

📦 Option C: Local Installation with npx

{
  "mcpServers": {
    "mcp-credentials-server": {
      "command": "npx",
      "args": ["mcp-credentials-server"],
      "env": {
        "MCP_ENCRYPTION_KEY": "your-32-character-encryption-key-here",
        "NODE_ENV": "production"
      }
    }
  }
}

🛠️ Option D: Development Mode (From Source)

{
  "mcpServers": {
    "mcp-credentials-server": {
      "command": "node",
      "args": ["/path/to/mcp-credentials-server/dist/server/index.js"],
      "env": {
        "MCP_ENCRYPTION_KEY": "your-32-character-encryption-key-here",
        "MCP_DEBUG": "true",
        "NODE_ENV": "development"
      }
    }
  }
}

⚙️ Environment Variables Explained

| Variable | Zero Config | Production Value | Development Value | Description | | -------------------- | --------------- | --------------------- | --------------------- | ----------------------------------------------------- | | MCP_ENCRYPTION_KEY | Auto-generated | your-32-char-key | your-32-char-key | 32-character encryption key (auto-generated if not set) | | NODE_ENV | not set | production | development | Controls debug output and performance | | MCP_DEBUG | false (default) | false (default) | true | Enable detailed logging (can override any mode) | | MCP_STORE_PATH | ~/.mcp-credentials | Custom path | Custom path | Storage directory for credentials | | MCP_PORT | 3000 (default) | 3000 (default) | 3000 (default) | Server port (usually not needed for MCP) | | MCP_HOST | localhost (default) | localhost (default) | localhost (default) | Server host (usually not needed for MCP) |

[Optional] Generate your encryption key (only if not using zero-config):

# Generate a secure 32-character encryption key
node -e "console.log(require('crypto').randomBytes(16).toString('hex'));"

# Or use openssl
openssl rand -hex 16

# Example output: a1b2c3d4e5f6789012345678901234ab

Restart Cursor completely to load the MCP server
Verify the configuration (optional):

# Test zero-config setup
mcp-credentials-server
# On first run, you'll see: "🔑 Generated new encryption key and saved to: ~/.mcp-credentials/.encryption-key"

# Test with custom key
NODE_ENV=production MCP_ENCRYPTION_KEY=your-key-here mcp-credentials-server

# You should see: "🚀 MCP Credentials Server started successfully"
# Press Ctrl+C to stop the test

🔧 Configuration Tips

🌟 Recommended: Zero Configuration

⚡ Simplest setup - Just specify the command, no env vars needed
🔐 Auto-security - Encryption key generated and saved automatically
🚀 Production ready - Optimized defaults with debug off
🛡️ Secure by default - Key file has proper permissions (600)
📁 Auto-setup - Creates storage directory automatically

🔧 Custom Configuration

🎛️ Use environment variables when you need specific control
🔑 Set MCP_ENCRYPTION_KEY for consistent keys across systems
🏭 Set NODE_ENV=production for explicit production mode
🛠️ Set NODE_ENV=development for development with debug logs
📂 Set MCP_STORE_PATH for custom storage location

🐛 Development & Debugging

🛠️ Use NODE_ENV=development for detailed logs
🔍 Use MCP_DEBUG=true for extra debugging (overrides NODE_ENV)
📝 Debug mode shows configuration details on startup
🔧 Use local path when developing the server itself

⚠️ Troubleshooting

🔍 Server doesn't start: Check file permissions on ~/.mcp-credentials/
🔍 Too verbose: Use zero-config (no env vars) or NODE_ENV=production
🔍 Need more logs: Add MCP_DEBUG=true to any configuration
🔍 Key issues: Delete ~/.mcp-credentials/.encryption-key to regenerate

Usage Examples

Once configured, you can ask Cursor:

"Set up my LinkedIn credentials with 2FA"
"Store my database connection details securely"
"Generate a 2FA code for GitHub"
"List all my configured services"

⚠️ Important Disclaimer

USE AT YOUR OWN RISK: This software handles sensitive credential information. While we implement industry-standard AES-256 encryption and security best practices, users are responsible for:

Keeping their encryption keys secure
Regularly backing up credential data
Ensuring compliance with their organization's security policies
Understanding that any AI system handling credentials carries inherent risks

Privacy Notice: All credentials are stored locally on your machine. No data is transmitted to external servers except when explicitly requested by AI actions you initiate.

🔐 Technical Overview

专为AI Agent设计的安全凭据管理系统，通过MCP (Model Context Protocol) 协议提供标准化的凭据获取和2FA处理功能。

✨ 核心特性

🤖 AI Agent友好: 专为AI Agent设计的MCP协议支持
🔒 军用级安全: AES-256加密存储，文件权限保护
🔐 智能2FA处理: 自动TOTP生成、备用代码管理、应用密码支持
🌐 多平台支持: LinkedIn、GitHub、数据库等主流服务
📊 完整审计: 详细的操作日志和访问记录
🔄 自动备份: 配置文件自动备份和恢复
🚀 开箱即用: 简单配置，立即可用

🎯 解决的核心问题

1. AI Agent凭据管理难题

问题: AI Agent需要访问各种服务（LinkedIn、数据库、API等），但凭据管理复杂且不安全。

解决方案: 提供统一的MCP接口，AI Agent通过标准化的function calls获取凭据。

// AI Agent简单调用
const credentials = await mcpCall('get_credentials', {
  service: 'linkedin',
  include2FA: true, // 自动处理2FA
});

// 自动获得登录信息和2FA代码
console.log(credentials.data.email); // 登录邮箱
console.log(credentials.twoFactorCode); // 自动生成的2FA代码

2. 2FA自动化处理挑战

问题: 大多数服务都要求2FA，传统自动化方案无法处理。

解决方案: 智能2FA处理策略，支持多种自动化方式：

🔐 TOTP自动生成

// 存储TOTP secret，自动生成验证码
{
  service: 'linkedin',
  twoFactor: {
    type: '2fa_totp',
    totpSecret: 'JBSWY3DPEHPK3PXP',  // 扫码获得的secret
    isActive: true
  }
}

// AI Agent自动获得6位验证码
const code = await mcpCall('generate_2fa', { service: 'linkedin' });
// 返回: { code: '123456', timeRemaining: 25 }

📝 备用代码管理

// 预存储备用验证码
{
  twoFactor: {
    type: '2fa_backup',
    backupCodes: ['12345678', '23456789', '34567890'],
    isActive: true
  }
}

// 自动使用并移除已用代码
const result = await mcpCall('generate_2fa', { service: 'github' });
// 返回: { code: '12345678', codesRemaining: 2 }

🔑 应用专用密码

// 某些服务支持应用专用密码（如GitHub）
{
  twoFactor: {
    type: '2fa_app_password',
    appPassword: 'ghp_xxxxxxxxxxxxxxxxxxxx',
    isActive: true
  }
}

// AI Agent直接使用应用密码，无需2FA

💾 会话持久化

// 保持长期有效的登录会话
{
  twoFactor: {
    type: '2fa_session_persist',
    sessionCookies: ['session=xxx', 'token=yyy'],
    isActive: true
  }
}

🚀 快速开始

安装

npm install @xiaoweihsueh/mcp-credentials-server

基础配置

import { MCPCredentialsServer } from '@xiaoweihsueh/mcp-credentials-server';

const server = new MCPCredentialsServer({
  port: 3000,
  storage: {
    storePath: '~/.mcp-credentials',
    encryptionKey: process.env.MCP_ENCRYPTION_KEY,
  },
  supported2FA: ['auto_totp', 'backup_codes', 'app_password'],
  debug: true,
});

await server.start();

设置服务凭据

// 设置LinkedIn凭据（带2FA）
await mcpCall('set_credentials', {
  service: 'linkedin',
  credentials: {
    email: '[email protected]',
    password: 'your-password',
    twoFactor: {
      type: '2fa_totp',
      totpSecret: 'JBSWY3DPEHPK3PXP', // 从LinkedIn 2FA设置获得
      isActive: true,
    },
  },
});

// 设置GitHub凭据（应用密码）
await mcpCall('set_credentials', {
  service: 'github',
  credentials: {
    token: 'ghp_xxxxxxxxxxxxxxxxxxxx',
    username: 'your-username',
    twoFactor: {
      type: '2fa_app_password',
      appPassword: 'ghp_xxxxxxxxxxxxxxxxxxxx',
      isActive: true,
    },
  },
});

🛠️ MCP Functions

1. get_credentials

获取服务凭据，自动处理2FA

const result = await mcpCall('get_credentials', {
  service: 'linkedin',
  profile: 'work',        // 可选，默认'default'
  include2FA: true        // 可选，是否生成2FA代码
});

// 返回
{
  success: true,
  data: {
    service: 'linkedin',
    email: '[email protected]',
    password: 'your-password',
    twoFactor: { ... }
  },
  twoFactorCode: '123456',  // 自动生成的2FA代码
  timestamp: '2025-10-10T12:00:00.000Z'
}

2. set_credentials

设置或更新服务凭据

await mcpCall('set_credentials', {
  service: 'postgres',
  credentials: {
    host: 'localhost',
    port: 5432,
    username: 'admin',
    password: 'secret',
    database: 'mydb',
  },
  profile: 'production',
});

3. generate_2fa

单独生成2FA代码

const result = await mcpCall('generate_2fa', {
  service: 'linkedin',
  profile: 'work'
});

// 返回
{
  success: true,
  code: '123456',
  codesRemaining: 5,      // 如果使用备用代码
  nextCodeIn: 25,         // TOTP下次更新秒数
  timestamp: '2025-10-10T12:00:00.000Z'
}

4. validate_credentials

验证凭据配置完整性

const result = await mcpCall('validate_credentials', {
  service: 'linkedin'
});

// 返回
{
  success: true,
  valid: true,
  details: {
    requiredFields: ['email', 'password'],
    missingFields: [],
    has2FA: true,
    lastUpdated: '2025-10-10T12:00:00.000Z'
  }
}

5. list_services

列出所有配置的服务

const result = await mcpCall('list_services', {
  profile: 'work'
});

// 返回
{
  services: ['linkedin', 'github', 'postgres'],
  count: 3,
  timestamp: '2025-10-10T12:00:00.000Z'
}

🔐 2FA配置指南

LinkedIn 2FA Setup - Complete Step-by-Step Guide

Step 1: Enable 2FA on LinkedIn

Access LinkedIn Security Settings:
- Log into LinkedIn.com in your web browser
- Click your profile picture → "Settings & Privacy"
- Navigate to "Sign in & security" in the left sidebar
- Find the "Two-step verification" section
Start 2FA Setup:
- Click "Turn on" (or "Change" if already enabled)
- LinkedIn will ask you to verify your identity first
- Choose "Authenticator app" as your preferred method

Step 2: Get the TOTP Secret Key

When LinkedIn shows the QR code setup screen:

Look for the manual setup option:
- Find and click "Can't scan?" or "Enter code manually" link
- This reveals the text version of the secret
Copy the secret key:
```
Example: JBSWY3DPEHPK3PXP2Q4B7Z8A9C1D2E3F
```
Alternative method (if manual option isn't visible):
- Right-click the QR code → "Copy image"
- Use an online QR decoder or QR scanner app
- Look for a URL like: otpauth://totp/LinkedIn:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=LinkedIn
- Extract the secret= parameter value

Step 3: Configure with MCP Server

Ask Cursor to set up your LinkedIn credentials:

Set up my LinkedIn credentials with TOTP 2FA:
- Email: [email protected]
- Password: your-linkedin-password
- TOTP Secret: JBSWY3DPEHPK3PXP2Q4B7Z8A9C1D2E3F

Or use this format for the credential object:

{
  service: 'linkedin',
  email: '[email protected]',
  password: 'your-linkedin-password',
  twoFactor: {
    type: '2fa_totp',
    totpSecret: 'JBSWY3DPEHPK3PXP2Q4B7Z8A9C1D2E3F',
    isActive: true
  }
}

Step 4: Complete LinkedIn Setup

Test the MCP server: Ask Cursor to "Generate a 2FA code for LinkedIn"
Enter the generated code into LinkedIn to complete the setup
Save the backup codes LinkedIn provides as a fallback
Click "Done" to finish the setup

Step 5: Verify Everything Works

Test your complete setup:

Get my LinkedIn credentials with 2FA code

Expected response:

{
  "success": true,
  "data": {
    "email": "[email protected]",
    "password": "your-linkedin-password",
    "twoFactor": { "type": "2fa_totp", "isActive": true }
  },
  "twoFactorCode": "123456",
  "timestamp": "2025-10-10T12:00:00.000Z"
}

🔒 Security Best Practices

Keep your TOTP secret secure - treat it like a password
Store LinkedIn's backup codes in a safe place (not in the MCP server)
Test before automation - verify the setup works before using it in scripts
Consider a separate account for automation to protect your main LinkedIn profile
Be aware of LinkedIn's terms regarding automated access

🚨 Common Issues

"Invalid code" errors:
- Check your system time is synchronized
- Verify the secret was copied correctly
- Try generating a new code (they change every 30 seconds)
QR code doesn't show manual option:
- Try different browsers (Chrome, Firefox, Safari)
- Disable ad blockers temporarily
- Use mobile LinkedIn app which sometimes has different options
LinkedIn security alerts:
- LinkedIn may flag automated login attempts
- Use the same browser/device for initial setup and automation
- Consider adding your IP to LinkedIn's trusted devices

GitHub应用密码

生成Personal Access Token
- GitHub → Settings → Developer settings → Personal access tokens
- 生成新token，选择所需权限

配置应用密码模式

{
  token: 'ghp_xxxxxxxxxxxxxxxxxxxx',
  twoFactor: {
    type: '2fa_app_password',
    appPassword: 'ghp_xxxxxxxxxxxxxxxxxxxx',
    isActive: true
  }
}

备用代码策略

收集备用代码
- 在各服务的2FA设置中下载备用代码
- 通常是8-10位数字

配置备用代码池

{
  twoFactor: {
    type: '2fa_backup',
    backupCodes: [
      '12345678',
      '23456789',
      '34567890'
    ],
    isActive: true
  }
}

🤖 AI Agent集成示例

自动LinkedIn发帖

class LinkedInAgent {
  async postUpdate(message: string) {
    // 1. 获取凭据和2FA代码
    const creds = await mcpCall('get_credentials', {
      service: 'linkedin',
      include2FA: true,
    });

    // 2. 自动登录（集成Chrome DevTools MCP）
    await browser.navigate('https://linkedin.com/login');
    await browser.fill('#username', creds.data.email);
    await browser.fill('#password', creds.data.password);
    await browser.click('button[type="submit"]');

    // 3. 处理2FA（如果需要）
    if (creds.twoFactorCode) {
      await browser.fill('input[name="pin"]', creds.twoFactorCode);
      await browser.click('button[type="submit"]');
    }

    // 4. 发布帖子
    await browser.click('[data-test-id="share-box-trigger"]');
    await browser.fill('[data-test-id="share-box-text-area"]', message);
    await browser.click('[data-test-id="share-button"]');

    console.log('✅ LinkedIn帖子发布成功!');
  }
}

数据库自动查询

class DatabaseAgent {
  async queryData(sql: string) {
    // 获取数据库凭据
    const creds = await mcpCall('get_credentials', {
      service: 'postgres',
      profile: 'production',
    });

    // 连接数据库
    const client = new pg.Client({
      host: creds.data.host,
      port: creds.data.port,
      user: creds.data.username,
      password: creds.data.password,
      database: creds.data.database,
      ssl: creds.data.ssl,
    });

    await client.connect();
    const result = await client.query(sql);
    await client.end();

    return result.rows;
  }
}

智能工作流编排

class ProjectWorkflow {
  async publishWeeklyReport() {
    // 1. 从数据库获取项目数据
    const projectData = await this.databaseAgent.queryData(`
      SELECT * FROM project_metrics
      WHERE date >= CURRENT_DATE - INTERVAL 7 DAYS
    `);

    // 2. 生成报告内容
    const report = this.generateReport(projectData);

    // 3. 发布到LinkedIn
    await this.linkedinAgent.postUpdate(report);

    // 4. 同步到GitHub Issues
    await this.githubAgent.createIssue('Weekly Report', report);

    console.log('✅ 周报发布工作流完成!');
  }
}

🛡️ 安全特性

加密存储

AES-256-GCM: 行业标准加密算法
随机盐值: 每个配置文件独立加密
文件权限: 配置文件仅当前用户可访问(600)

访问控制

// Agent权限控制
const agentContext = {
  agentId: 'marketing-bot',
  permissions: ['linkedin', 'twitter'], // 只能访问社交媒体
  sessionId: 'session-xxx',
};

审计日志

// 完整的操作审计
{
  id: 'audit-xxx',
  timestamp: '2025-10-10T12:00:00.000Z',
  action: 'get_credentials',
  service: 'linkedin',
  agentContext: { agentId: 'marketing-bot' },
  success: true,
  metadata: { profile: 'work' }
}

备份恢复

// 自动备份配置
{
  backupEnabled: true,
  backupInterval: 60,        // 60分钟
  retention: 10              // 保留10个备份
}

📁 项目结构

mcp-credentials-server/
├── src/
│   ├── server/           # MCP Server核心
│   │   └── mcp-server.ts
│   ├── auth/            # 2FA处理
│   │   └── 2fa-handler.ts
│   ├── storage/         # 存储层
│   │   └── credentials-storage.ts
│   └── types/           # 类型定义
│       └── index.ts
├── examples/            # 使用示例
│   └── ai-agent-usage.ts
├── docs/               # 文档
└── README.md

🔧 配置选项

interface MCPServerConfig {
  port?: number; // 服务端口，默认3000
  host?: string; // 服务地址，默认localhost
  storage: {
    storePath?: string; // 存储路径，默认~/.mcp-credentials
    encryptionKey?: string; // 加密密钥
    backupEnabled?: boolean; // 是否启用备份
    backupInterval?: number; // 备份间隔（分钟）
  };
  supported2FA?: string[]; // 支持的2FA策略
  sessionTimeout?: number; // 会话超时（分钟）
  debug?: boolean; // 调试模式
}

🚨 故障排除

常见问题

2FA代码无效

# 检查系统时间是否正确
ntpdate -s time.nist.gov

# 验证TOTP secret是否正确
node -e "
const handler = require('./dist/auth/2fa-handler');
console.log(handler.generateTOTP('YOUR_SECRET'));
"

凭据获取失败

// 验证凭据是否存在
const validation = await mcpCall('validate_credentials', {
  service: 'linkedin',
});
console.log(validation.details);

权限错误

# 检查配置文件权限
ls -la ~/.mcp-credentials/profiles/

# 修复权限
chmod 600 ~/.mcp-credentials/profiles/*.enc

🤝 与其他MCP工具集成

Chrome DevTools MCP

// 结合浏览器自动化
const browser = new ChromeDevToolsMCP();
const credentials = new MCPCredentialsServer();

// 自动化登录流程
async function autoLogin(service: string) {
  const creds = await credentials.getCredentials(service);

  await browser.navigate(getLoginURL(service));
  await browser.fill('#username', creds.data.email);
  await browser.fill('#password', creds.data.password);

  if (creds.twoFactorCode) {
    await browser.fill('#totp', creds.twoFactorCode);
  }

  await browser.click('#login-button');
}

Confluence MCP

// 自动发布文档
async function publishToConfluence(title: string, content: string) {
  const creds = await mcpCall('get_credentials', {
    service: 'confluence',
  });

  await confluenceMCP.authenticate(creds.data);
  await confluenceMCP.createPage(title, content);
}

📊 监控和指标

服务状态

const status = server.getStatus();
console.log(status);
// {
//   version: '1.0.0',
//   uptime: 3600,
//   stats: {
//     auditLogsCount: 150,
//     lastActivity: '2025-10-10T12:00:00.000Z'
//   }
// }

存储统计

const stats = await storage.getStats();
console.log(stats);
// {
//   profiles: 3,
//   totalServices: 12,
//   storageSize: 4096,
//   backupCount: 7
// }

🛣️ 发展路线图

[ ] v1.1: Web UI管理界面
[ ] v1.2: 云端同步支持
[ ] v1.3: 更多2FA方式（硬件密钥、生物识别）
[ ] v1.4: 企业级权限管理
[ ] v1.5: API密钥轮换自动化

📝 许可证

MIT License - 查看 LICENSE 文件了解详细信息。

🙏 致谢

感谢MCP协议的设计团队
感谢iTrade项目的测试和反馈
感谢所有贡献者的支持

核心价值: 让AI Agent能够安全、便捷地访问需要认证的服务，真正实现"AI驱动的全自动化"。

作者: Xiaowei Hsueh ([email protected]) 项目地址: https://github.com/hsuehic/mcp-credentials-server 技术支持: 欢迎提交Issues和Pull Requests