Duo API MCP服务器
MCP(模型上下文协议)服务器,用于与自动身份验证无缝集成Duo API。 内置Duo API认证,带有HMAC-SHA512签名。
快速开始
先决条件
- Node.js 18+和npm
- Duo API证书 (集成密钥、密钥、API主机名)
- 克劳德桌面 或其他MCP兼容客户端
1.设置开发环境```bash
Clone or download this repository
cd duo-api-mcp
Install dependencies
npm install
Build the TypeScript project
npm run build
### 2.配置Duo API凭据
创建或编辑 `environments/duo_api_env.json`:```json
{
"name": "Duo API Environment",
"values": [
{
"key": "ikey",
"value": "YOUR_INTEGRATION_KEY",
"type": "default",
"enabled": true
},
{
"key": "skey",
"value": "YOUR_SECRET_KEY",
"type": "secret",
"enabled": true
},
{
"key": "apihost",
"value": "api-xxxxxxxx.duosecurity.com",
"type": "default",
"enabled": true
}
]
}
在哪里可以获得这些凭据:
- 登录您的 Duo管理面板
- 首选 应用程序 → 保护应用程序
- 搜索 管理员API (或根据需要验证API/帐户API)
- 注意 集成密钥, 密钥,以及 API主机名
3.测试服务器```bash
Test build and basic functionality
npm run dev
You should see output like:
🚀 Starting Duo API MCP Server...
📚 Total API collections loaded: 5
🌐 Total environments loaded: 1
✅ Duo API MCP Server running on stdio
## 🔧 安装和配置
### 地方发展设置```bash
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode (rebuilds and runs)
npm run dev
# Run production build
npm start
作为服务运行
选项1:使用PM2(推荐)```bash
Install PM2 globally
npm install -g pm2
Start the service
pm2 start build/index.js --name "duo-api-mcp"
Save PM2 configuration
pm2 save
Setup auto-start on boot
pm2 startup
Monitor the service
pm2 status
pm2 logs duo-api-mcp
#### 选项2:使用systemd(Linux)
创建 `/etc/systemd/system/duo-api-mcp.service`:```ini
[Unit]
Description=Duo API MCP Server
After=network.target
[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/duo-api-mcp
ExecStart=/usr/bin/node build/index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.target
``````bash
# Enable and start the service
sudo systemctl enable duo-api-mcp
sudo systemctl start duo-api-mcp
sudo systemctl status duo-api-mcp
🖥️ 客户端配置
Claude桌面配置
添加到您的Claude桌面 claude_desktop_config.json:
地方发展```json
{
"mcpServers": {
"duo-api": {
"command": "node",
"args": ["/absolute/path/to/duo-api-mcp/build/index.js"],
"env": {
"NODE_ENV": "development"
}
}
}
}
#### 生产服务```json
{
"mcpServers": {
"duo-api": {
"command": "node",
"args": ["/absolute/path/to/duo-api-mcp/build/index.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
Claude Desktop配置文件位置:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
其他MCP客户端
对于其他MCP兼容客户端,请使用stdio传输:```bash
Direct execution
node /path/to/duo-api-mcp/build/index.js
With environment variables
NODE_ENV=production node /path/to/duo-api-mcp/build/index.js
## 🔐 Duo API身份验证
此服务器提供 **自动Duo API身份验证** 处理Duo的API安全性的所有复杂签名要求。
- ✅ **自动检测** 的Duo API请求
- ✅ **HMAC-SHA512** 签名生成
- ✅ **变量替换** 获取凭据
- ✅ **兼容** 具有所有Duo API(管理员、身份验证、帐户)
**📖 看 DUO_认证.md 了解详细的设置和使用方法。**
## 🔒 SSL证书处理
默认情况下,服务器 **禁用SSL证书验证** 以避免自签名证书或开发环境的问题。此配置可以更改:
### 默认行为
- ⚠️ **SSL验证已禁用** (开发模式)
- 使用自签名证书
- 绕过证书颁发机构验证
- 适用于开发和测试
### 启用严格的SSL(生产)
使用 `configure-ssl` 启用严格证书验证的工具:```
Tool: configure-ssl
- strictSSL: true
当前SSL状态
使用以下工具检查当前SSL配置:```
Tool: get-server-status
## 🔄 自动加载API集合和环境
服务器在启动时自动发现并加载API集合和环境:
### 目录结构```
duo-api-mcp/
├── collections/ # Place your API collection .json files here
├── environments/ # Place your environment .json files here
└── examples/ # Sample files (also scanned)
重要:服务器查找与其自己的安装目录相关的集合,而不是与Claude Desktop的工作目录相关的。这确保了无论Claude Desktop从何处运行,都能找到集合。
什么会自动加载
- API集合:全部
.json文件在./collections/和./examples/目录(相对于服务器) - 环境:文件名中包含“environment”或“env”的文件
- 验证:仅加载有效的集合/环境格式
特性
特性
- 自动发现:启动时自动加载所有API集合和环境
- Duo API身份验证:所有Duo API调用的内置HMAC-SHA512签名
- 多个API:支持管理员API、Auth API和帐户API
- 环境管理:从JSON文件自动加载配置
- 可变分辨率:自动替换{{variable}}语法
- 错误处理:通过Duo特定的诊断功能增强错误报告
- SSL灵活性:用于开发/生产环境的可配置证书验证
可用工具
核心API工具
list-available-apis
显示所有可用的API集合及其终结点。
list-api-endpoints
列出特定API集合中的所有终结点。
collectionName:要列出终结点的API集合的名称
call-api
对特定终结点执行API调用。
collectionName:API集合的名称endpointName:要调用的API终结点的名称environment:配置的可选环境名称variables:要为此API调用覆盖的可选变量
管理工具
get-server-status
显示当前服务器状态,包括所有自动加载的集合和环境。
refresh-api-collections
刷新并重新加载所有API集合和环境,而无需重新启动服务器。
configure-ssl
配置SSL证书验证设置。
strictSSL:启用(true)或禁用(false)SSL证书验证
环境管理
load-environment (手动)
从JSON文件加载环境配置(自动加载的替代方案)。
filePath:环境JSON文件的路径environmentName:引用此环境的名称
list-environments
列出所有加载的环境配置。
基本用法
工作流示例
- 检查可用的API:```
Tool: list-available-apis
1. **列出集合中的终结点**:```
Tool: list-api-endpoints
- collectionName: "Duo Admin API"
- 执行API调用:```
Tool: call-api
- collectionName: "Duo Admin API"
- endpointName: "Get Users"
- environment: "Duo API Environment"
1. **添加环境** (可选):将环境文件放置在 `./environments/` 目录
1. **启动服务器**:集合在启动时自动加载
1. **检查状态**:使用 `get-server-status` 查看加载内容的工具
1. **浏览API**:使用 `list-available-apis` 查看可用收藏
1. **执行通话**:使用 `call-api` 具有所需端点的工具
### 工作流示例
1. **检查可用的API**:```
Tool: list-available-apis
- 列出集合中的终结点:```
Tool: list-api-endpoints
- collectionName: "Duo Admin API v4.1.0"
1. **执行API调用**:```
Tool: call-api
- collectionName: "Duo Admin API v4.1.0"
- endpointName: "Get Users"
- environment: "dev-environment"
可用脚本
npm run build-将TypeScript编译为JavaScriptnpm run start-运行已编译的API服务器npm run dev-构建并运行开发模式npm run setup-claude-自动配置克劳德桌面(macOS/Linux)npm run test-setup-验证安装和设置
安装和设置
- 构建项目:```bash
npm run build
1. 配置您的MCP客户端以使用此服务器:```json
{
"mcpServers": {
"duo-apis": {
"command": "node",
"args": ["/absolute/path/to/build/index.js"]
}
}
}
快速设置
自动设置(推荐)
运行自动安装脚本以构建项目并配置Claude Desktop:```bash
On macOS/Linux
npm run setup-claude
On Windows (PowerShell)
npm run build
.\scripts\setup-claude.ps1
此脚本将:
- 构建TypeScript项目
- 创建或更新您的Claude Desktop配置
- 备份任何现有配置
- 提供测试的后续步骤
### 手动设置
## Claude桌面配置
要将此MCP服务器与Claude Desktop一起使用,请将以下内容添加到您的 `claude_desktop_config.json`:```json
{
"mcpServers": {
"duo-apis": {
"command": "node",
"args": ["/Users/rmarther/src/duo/duo_api_mcp/build/index.js"]
}
}
}
备注:更新中的路径 args 数组以匹配您的实际安装目录。
支持的邮递员功能
- ✅ 集合变量
- ✅ 环境变量
- ✅ 用{{Variable}}语法替换变量
- ✅ 承载令牌身份验证
- ✅ 基本身份验证
- ✅ API密钥验证
- ✅ 原始请求正文
- ✅ 表单数据体
- ✅ URL编码体
- ✅ 自定义头
- ✅ 查询参数
需求
- Node.js 18+
- TypeScript
- 邮差收藏格式v2.1+
发展```bash
Install dependencies
npm install
Build the project
npm run build
Run in development mode
npm run dev
## 许可证
国际协调委员会
## 🛠️ 故障排除
### 常见问题
#### “用户API客户端不可用”
此错误通常表示凭据问题:
1. **检查凭据**:验证您的 `ikey`, `skey`,以及 `apihost` 在环境文件中
1. **真实与测试证书**:确保您没有使用演示/示例凭据
1. **API权限**:验证您的集成是否具有端点的权限
1. **网络连接**:测试是否可以访问API主机名```bash
# Test credentials manually
curl -H "Authorization: Basic $(echo -n 'ikey:skey' | base64)" \
https://your-api-host/admin/v1/info
“未找到收藏”
- 跑
refresh-api-collections重新加载集合的工具 - 检查一下
.json文件位于collections/目录 - 使用以下命令验证JSON语法:
node -e "JSON.parse(require('fs').readFileSync('collections/your-file.json'))"
“未加载环境”
- 环境文件的文件名中必须包含“Environment”或“env”
- 检查JSON语法:缺少逗号、尾随逗号等。
- 使用
list-environments查看加载内容的工具
Claude桌面连接问题
- 验证中的绝对路径
claude_desktop_config.json - 检查生成目录是否存在:
ls -la build/index.js - 配置更改后重新启动Claude Desktop
- 检查Claude Desktop日志中的连接错误
调试模式
通过设置环境变量启用详细日志记录:```bash
Development mode with extra logging
NODE_ENV=development DEBUG=* node build/index.js
Check what collections/environments are loaded
node build/index.js 2>&1 | grep -E "(Loaded|collections|environments)"
### 验证命令```bash
# Verify build
npm run build && echo "✅ Build successful" || echo "❌ Build failed"
# Test environment file syntax
node -e "console.log('✅ Environment valid:', JSON.parse(require('fs').readFileSync('environments/duo_api_env.json')))"
# List all available endpoints
node -e "
const fs = require('fs');
const files = fs.readdirSync('collections').filter(f => f.endsWith('.json'));
files.forEach(f => {
try {
const c = JSON.parse(fs.readFileSync(\`collections/\${f}\`));
console.log(\`📚 \${c.info.name}: \${c.item.length} items\`);
} catch(e) { console.log(\`❌ \${f}: \${e.message}\`); }
});
"
📊 监控和日志
服务器状态
使用内置工具监视服务器:```
Tool: get-server-status
显示:
- 加载的集合和环境
- SSL配置
- 搜索目录
- 配置摘要
### 日志位置
#### 发展
直接运行时,日志会输出到stderr:```bash
node build/index.js 2> server.log
PM2服务```bash
pm2 logs duo-api-mcp
pm2 logs duo-api-mcp --lines 100
#### 系统化服务```bash
sudo journalctl -u duo-api-mcp -f
sudo journalctl -u duo-api-mcp --since "1 hour ago"
🔄 更新和维护
更新服务器```bash
Pull latest changes (if using git)
git pull
Reinstall dependencies
npm install
Rebuild
npm run build
Restart service
pm2 restart duo-api-mcp
OR
sudo systemctl restart duo-api-mcp
```
添加新的API集合
- 地方
.json收集文件collections/目录 - 使用
refresh-api-collections无需重新启动即可重新加载的工具 - 证实
list-available-apis工具
环境更新
- 编辑文件
environments/目录 - 使用
refresh-api-collections重新加载工具 - 证实
list-environments工具
📋 可用脚本
npm run build-将TypeScript编译为JavaScriptnpm run start-运行已编译的API服务器npm run dev-构建并运行开发模式npm run setup-claude-自动克劳德桌面设置(如果可用)npm test-运行测试(如果已配置)
🔗 相关文件
- DUO_认证.md -详细的身份验证指南
- POSTMAN_ABSTRACTION.md -技术实施细节
- 集合/README.md -收藏管理
- 环境/README.md -环境配置
📝 许可证
国际协调委员会
🆘 支持
对于以下问题:
- Duo API:检查 Duo的官方文件
- MCP协议:参见 模型上下文协议文档
- 此服务器:检查上面的故障排除部分或创建问题
