Content
# MCP Credentials Server
🔐 **Secure Credential Management for AI Agents via Model Context Protocol**
[](https://github.com/hsuehic/mcp-credentials-server/actions/workflows/ci.yml)
[](https://github.com/hsuehic/mcp-credentials-server/actions/workflows/release.yml)
[](https://badge.fury.io/js/mcp-credentials-server)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
---
## 🚀 Quick Start for End Users
### Installation
```bash
# 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)**
```json
{
"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)**
```json
{
"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**
```json
{
"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)**
```json
{
"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) |
4. **[Optional] Generate your encryption key** (only if not using zero-config):
```bash
# 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
```
5. **Restart Cursor** completely to load the MCP server
6. **Verify the configuration** (optional):
```bash
# 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获取凭据。
```typescript
// 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自动生成
```typescript
// 存储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 }
```
#### 📝 备用代码管理
```typescript
// 预存储备用验证码
{
twoFactor: {
type: '2fa_backup',
backupCodes: ['12345678', '23456789', '34567890'],
isActive: true
}
}
// 自动使用并移除已用代码
const result = await mcpCall('generate_2fa', { service: 'github' });
// 返回: { code: '12345678', codesRemaining: 2 }
```
#### 🔑 应用专用密码
```typescript
// 某些服务支持应用专用密码（如GitHub）
{
twoFactor: {
type: '2fa_app_password',
appPassword: 'ghp_xxxxxxxxxxxxxxxxxxxx',
isActive: true
}
}
// AI Agent直接使用应用密码，无需2FA
```
#### 💾 会话持久化
```typescript
// 保持长期有效的登录会话
{
twoFactor: {
type: '2fa_session_persist',
sessionCookies: ['session=xxx', 'token=yyy'],
isActive: true
}
}
```
## 🚀 快速开始
### 安装
```bash
npm install @xiaoweihsueh/mcp-credentials-server
```
### 基础配置
```typescript
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();
```
### 设置服务凭据
```typescript
// 设置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
```typescript
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
设置或更新服务凭据
```typescript
await mcpCall('set_credentials', {
service: 'postgres',
credentials: {
host: 'localhost',
port: 5432,
username: 'admin',
password: 'secret',
database: 'mydb',
},
profile: 'production',
});
```
### 3. generate_2fa
单独生成2FA代码
```typescript
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
验证凭据配置完整性
```typescript
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
列出所有配置的服务
```typescript
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](https://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
2. **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
2. **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**:
```typescript
{
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**:
```json
{
"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)
2. **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
3. **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，选择所需权限
2. **配置应用密码模式**
```typescript
{
token: 'ghp_xxxxxxxxxxxxxxxxxxxx',
twoFactor: {
type: '2fa_app_password',
appPassword: 'ghp_xxxxxxxxxxxxxxxxxxxx',
isActive: true
}
}
```
### 备用代码策略
1. **收集备用代码**
- 在各服务的2FA设置中下载备用代码
- 通常是8-10位数字
2. **配置备用代码池**
```typescript
{
twoFactor: {
type: '2fa_backup',
backupCodes: [
'12345678',
'23456789',
'34567890'
],
isActive: true
}
}
```
## 🤖 AI Agent集成示例
### 自动LinkedIn发帖
```typescript
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帖子发布成功!');
}
}
```
### 数据库自动查询
```typescript
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;
}
}
```
### 智能工作流编排
```typescript
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)
### 访问控制
```typescript
// Agent权限控制
const agentContext = {
agentId: 'marketing-bot',
permissions: ['linkedin', 'twitter'], // 只能访问社交媒体
sessionId: 'session-xxx',
};
```
### 审计日志
```typescript
// 完整的操作审计
{
id: 'audit-xxx',
timestamp: '2025-10-10T12:00:00.000Z',
action: 'get_credentials',
service: 'linkedin',
agentContext: { agentId: 'marketing-bot' },
success: true,
metadata: { profile: 'work' }
}
```
### 备份恢复
```typescript
// 自动备份配置
{
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
```
## 🔧 配置选项
```typescript
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代码无效**
```bash
# 检查系统时间是否正确
ntpdate -s time.nist.gov
# 验证TOTP secret是否正确
node -e "
const handler = require('./dist/auth/2fa-handler');
console.log(handler.generateTOTP('YOUR_SECRET'));
"
```
2. **凭据获取失败**
```typescript
// 验证凭据是否存在
const validation = await mcpCall('validate_credentials', {
service: 'linkedin',
});
console.log(validation.details);
```
3. **权限错误**
```bash
# 检查配置文件权限
ls -la ~/.mcp-credentials/profiles/
# 修复权限
chmod 600 ~/.mcp-credentials/profiles/*.enc
```
## 🤝 与其他MCP工具集成
### Chrome DevTools MCP
```typescript
// 结合浏览器自动化
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
```typescript
// 自动发布文档
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);
}
```
## 📊 监控和指标
### 服务状态
```typescript
const status = server.getStatus();
console.log(status);
// {
// version: '1.0.0',
// uptime: 3600,
// stats: {
// auditLogsCount: 150,
// lastActivity: '2025-10-10T12:00:00.000Z'
// }
// }
```
### 存储统计
```typescript
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](LICENSE) 文件了解详细信息。
## 🙏 致谢
- 感谢MCP协议的设计团队
- 感谢iTrade项目的测试和反馈
- 感谢所有贡献者的支持
---
**核心价值**: 让AI Agent能够安全、便捷地访问需要认证的服务，真正实现"AI驱动的全自动化"。
**作者**: Xiaowei Hsueh (<xiaoweihsueh@gmail.com>)
**项目地址**: <https://github.com/hsuehic/mcp-credentials-server>
**技术支持**: 欢迎提交Issues和Pull Requests
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available