MCP Credentials Server

MCP Credentials Server

🔐 Secure Credential Management for AI Agents via Model Context Protocol

  ](https://badge.fury.io/js/mcp-credentials-server)  ](https://nodejs.org/)

🚀 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

1. Open Cursor Settings (Cmd+, on Mac, Ctrl+, on Windows/Linux)
2. Search for "MCP" in settings
3. 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

1. [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

1. Restart Cursor completely to load the MCP server

1. 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: 'your@email.com',
    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: 'your@email.com',
    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

1. 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

1. 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:

1. 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

1. 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:you@example.com?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: your-email@example.com
- Password: your-linkedin-password
- TOTP Secret: JBSWY3DPEHPK3PXP2Q4B7Z8A9C1D2E3F

Or use this format for the credential object:

{
  service: 'linkedin',
  email: 'your-email@example.com',
  password: 'your-linkedin-password',
  twoFactor: {
    type: '2fa_totp',
    totpSecret: 'JBSWY3DPEHPK3PXP2Q4B7Z8A9C1D2E3F',
    isActive: true
  }
}

Step 4: Complete LinkedIn Setup

1. Test the MCP server: Ask Cursor to "Generate a 2FA code for LinkedIn"
2. Enter the generated code into LinkedIn to complete the setup
3. Save the backup codes LinkedIn provides as a fallback
4. 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": "your-email@example.com",
    "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

1. "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)

1. 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

1. 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应用密码

1. 生成Personal Access Token

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

1. 配置应用密码模式

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

备用代码策略

1. 收集备用代码

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

1. 配置备用代码池

   {
     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; // 调试模式
}

🚨 故障排除

常见问题

1. 2FA代码无效

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

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

1. 凭据获取失败

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

1. 权限错误

   # 检查配置文件权限
   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 () 项目地址: 技术支持: 欢迎提交Issues和Pull Requests