Duo API MCP

Duo API MCP服务器

MCP（模型上下文协议）服务器，用于与自动身份验证无缝集成Duo API。 内置Duo API认证，带有HMAC-SHA512签名。

� 快速开始

先决条件

• Node.js 18+和npm
• Duo API证书 （集成密钥、密钥、API主机名）
• 克劳德桌面 或其他MCP兼容客户端

1.设置开发环境

# 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:

{
  "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
    }
  ]
}

在哪里可以获得这些凭据：

1. 登录您的 Duo管理面板
2. 首选 应用程序 → 保护应用程序
3. 搜索 管理员API （或根据需要验证API/帐户API）
4. 注意 集成密钥, 密钥，以及 API主机名

3.测试服务器

# 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

🔧 安装和配置

地方发展设置

# 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（推荐）

# 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:

[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

# 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:

地方发展

{
  "mcpServers": {
    "duo-api": {
      "command": "node",
      "args": ["/absolute/path/to/duo-api-mcp/build/index.js"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

生产服务

{
  "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传输：

# 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

列出所有加载的环境配置。

基本用法

工作流示例

1. 检查可用的API:

   Tool: list-available-apis

1. 列出集合中的终结点:

   Tool: list-api-endpoints
   - collectionName: "Duo Admin API"

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

1. 列出集合中的终结点:

   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编译为JavaScript
• npm run start -运行已编译的API服务器
• npm run dev -构建并运行开发模式
• npm run setup-claude -自动配置克劳德桌面（macOS/Linux）
• npm run test-setup -验证安装和设置

安装和设置

1. 构建项目：

   npm run build

1. 配置您的MCP客户端以使用此服务器：

   {
     "mcpServers": {
       "duo-apis": {
         "command": "node",
         "args": ["/absolute/path/to/build/index.js"]
       }
     }
   }

快速设置

自动设置（推荐）

运行自动安装脚本以构建项目并配置Claude Desktop：

# 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:

{
  "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+

发展

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

许可证

国际协调委员会

🛠️ 故障排除

常见问题

“用户API客户端不可用”

此错误通常表示凭据问题：

1. 检查凭据：验证您的 ikey, skey，以及 apihost 在环境文件中
2. 真实与测试证书：确保您没有使用演示/示例凭据
3. API权限：验证您的集成是否具有端点的权限
4. 网络连接：测试是否可以访问API主机名

# 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日志中的连接错误

调试模式

通过设置环境变量启用详细日志记录：

# 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)"

验证命令

# 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：

node build/index.js 2> server.log

PM2服务

pm2 logs duo-api-mcp
pm2 logs duo-api-mcp --lines 100

系统化服务

sudo journalctl -u duo-api-mcp -f
sudo journalctl -u duo-api-mcp --since "1 hour ago"

🔄 更新和维护

更新服务器

# 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集合

1. 地方 .json 收集文件 collections/ 目录
2. 使用 refresh-api-collections 无需重新启动即可重新加载的工具
3. 证实 list-available-apis 工具

环境更新

1. 编辑文件 environments/ 目录
2. 使用 refresh-api-collections 重新加载工具
3. 证实 list-environments 工具

📋 可用脚本

• npm run build -将TypeScript编译为JavaScript
• npm 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协议：参见 模型上下文协议文档
• 此服务器：检查上面的故障排除部分或创建问题