Directadmin

DirectAdmin MCP 服务

用于集成 DirectAdmin 的模型上下文协议（MCP）服务，让 AI 助手能够通过自然语言与 DirectAdmin 交互。

功能

• MCP 集成：使用模型上下文协议将 AI 助手连接到 DirectAdmin
• RESTful API：用于管理 DirectAdmin 的综合 API
• 服务器发送事件（SSE）：与客户端实时通信
• 基于工具的架构：采用基于工具命令的模块化设计
• 命令行客户端：附带用于测试和编写脚本的客户端
• Docker 支持：通过 Docker 和 Docker Compose 轻松部署

架构

本项目实现了一个充当 AI 助手与 DirectAdmin 之间桥梁的服务：

┌──────────┐     ┌─────────────────┐     ┌────────────┐
│   AI     │     │  DirectAdmin    │     │ DirectAdmin│
│ Assistant├────►│  MCP Server     ├────►│   API      │
└──────────┘     └─────────────────┘     └────────────┘
      MCP                SSE                 HTTP

该服务通过基于工具的接口提供 DirectAdmin 功能，让 AI 助手能够轻松理解并与 DirectAdmin 操作交互。

前提条件

• Python 3.12+
• 可访问 API 的 DirectAdmin 服务
• DirectAdmin 登录密钥（首选）或用户名／密码

安装

选项 1：标准安装

1. 克隆代码库：

   git clone https://github.com/omryatia/directadmin-mcp.git
   cd directadmin-mcp
   

2. 创建虚拟环境：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. 安装依赖：

   pip install -r requirements.txt
   

4. 创建配置：

   cp .gitignore.sample .gitignore
   cp .env.sample .env
   # Edit .env with your DirectAdmin settings
   

选项 2：Docker 安装

1. 克隆代码库：

   git clone https://github.com/omryatia/directadmin-mcp.git
   cd directadmin-mcp
   

2. 创建配置：

   cp .env.sample .env
   # Edit .env with your DirectAdmin settings
   

3. 使用 Docker Compose 构建并启动：

   docker-compose up -d
   

配置

编辑 .env 文件，填入 DirectAdmin 凭据：

# DirectAdmin Settings
DA_URL=https://your-directadmin-server:2222
DA_USERNAME=admin
DA_LOGIN_KEY=your_directadmin_login_key_here/password

# Server Settings
PORT=8888
LOG_LEVEL=INFO
DEBUG=false

# SSL Settings
SSL_VERIFY=true

配置选项

变量	描述	默认值
DA_URL	DirectAdmin 服务 URL（含端口）	（必填）
DA_USERNAME	DirectAdmin 用户名	（必填）
DA_LOGIN_KEY	DirectAdmin 登录密钥	（必填）
PORT	MCP 服务运行端口	8888
LOG_LEVEL	日志级别（DEBUG、INFO、WARNING、ERROR）	INFO
DEBUG	为开发启用调试模式	false
SSL_VERIFY	验证 DirectAdmin API 调用的 SSL 证书	true

使用方法

启动服务

你可以通过以下两种方式启动服务：

1. 使用支持 SSE 的 FastAPI（推荐）：

   python main.py
   

2. 使用简单的 MCP 服务：

   python server.py
   

默认情况下，服务将在 8888 端口启动（可在 .env 中配置）。

使用命令行客户端

附带的命令行客户端可让你与 MCP 服务交互：

# Get server info
python client.py --info

# Check server health
python client.py --health

# Send a specific message
python client.py "Show me the version of DirectAdmin"

# Interactive mode
python client.py

客户端选项

选项	描述
--server、-s	MCP 服务 URL
--key、-k	用于身份验证的 API 密钥
--no-verify	禁用 SSL 验证
--timeout、-t	请求超时时间（秒）
--info、-i	获取服务信息
--health	检查服务运行状况

连接 AI 助手

配置 AI 助手以使用 MCP 端点：

http://your-server:8888/sse

这样 AI 助手就可以：

1. 查询 DirectAdmin 信息
2. 执行 DirectAdmin 命令
3. 接收实时更新

可用工具

该服务将以下 DirectAdmin 操作作为工具提供：

系统管理

• api_restart：重启 DirectAdmin
• api_ping：检查 DirectAdmin 是否正在运行

版本控制

• api_get_version：获取 DirectAdmin 版本信息
• api_version_update：将 DirectAdmin 更新到最新版本
• api_change_update_channel：更改更新频道

系统更新

• api_system_packages_updates：获取可用的系统软件包更新
• api_system_packages_update_test：测试系统软件包更新
• api_system_packages_update_run：运行系统软件包更新

安全

• api_security_txt_status：检查 security.txt 状态
• api_security_txt_get：获取 security.txt 内容
• api_security_txt_update：更新 security.txt 内容

API 端点

端点	方法	描述
/	GET	显示 HTML 欢迎消息的根页面
/about	GET	服务信息
/health	GET	健康检查端点
/sse	GET	MCP SSE 连接端点
/messages	POST	用于发布 SSE 消息的内部端点

开发

项目结构

directadmin-mcp/
├── README.md               # Project documentation
├── .env.sample             # Environment variables template
├── config.py               # Configuration module
├── main.py                 # FastAPI application with SSE support
├── server.py               # Simple MCP server
├── client.py               # Command-line client
├── da.py                   # DirectAdmin API client
├── mcp_instance.py         # MCP instance configuration
├── tools/                  # Tool modules directory
│   ├── __init__.py         # Tool loading mechanism
│   ├── common.py           # Common tool utilities
│   ├── misc.py             # Misc DirectAdmin operations
│   ├── security_txt.py     # Security.txt related tools
│   ├── system_update.py    # System update tools
│   └── versioning.py       # Versioning and update tools
│   └── and alot more ......
└── requirements.txt        # Project dependencies

添加新工具

1. 在 tools 目录中创建或编辑文件
2. 使用 @mcp.tool() 装饰器添加新函数：

import logging
from mcp_instance import mcp
from da import call_da_api
from tools.common import log_tool_call, format_response

@mcp.tool()
@log_tool_call
async def my_new_tool(param1, param2):
    """
    Tool documentation.
    
    Args:
        param1: First parameter description
        param2: Second parameter description
        
    Returns:
        Description of the return value
    """
    # Implementation
    response = await call_da_api("/api/endpoint", method="GET")
    return format_response(response)

服务器启动时会自动发现并注册该工具。

日志记录

服务器使用完善的日志记录系统：

• 控制台日志：显示在终端中
• 文件日志：写入 logs 目录
• 错误日志：单独的文件，用于跟踪错误

可以在 .env 文件中通过 LOG_LEVEL 变量配置日志级别。

Docker 部署

项目支持 Docker，便于部署：

# Build the image
docker build -t directadmin-mcp .

# Run the container
docker run -d \
  -p 8888:8888 \
  --env-file .env \
  --name directadmin-mcp \
  directadmin-mcp

也可以使用 Docker Compose 简化操作：

docker-compose up -d

安全注意事项

• 在生产环境中使用带有效 SSL 证书的 HTTPS
• 设置适当的防火墙规则以限制访问
• 使用配置了适当安全标头的反向代理（如 Nginx）
• 妥善保管 DirectAdmin 登录密钥并定期轮换
• 考虑在生产环境中为 MCP 服务添加身份验证

故障排除

连接问题

如果遇到连接问题：

1. 确认 DirectAdmin 服务可访问
2. 检查 DirectAdmin API 凭据是否正确
3. 确保已启用 DirectAdmin API
4. 如果使用 HTTPS，请检查 SSL 设置

常见错误消息

• “身份验证失败”：检查 DirectAdmin 凭据
• “SSL 验证失败”：在 .env 中设置 SSL_VERIFY=false，或修复证书
• “未找到工具”：确保已正确加载工具模块
• “连接被拒绝”：检查 DirectAdmin 是否正在运行且可访问

贡献

欢迎贡献！请随时提交 Pull Request。

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

致谢

• Model Context Protocol
• DirectAdmin
• DirectAdmin Api Swagger
• DirectAdmin Api Swagger Json
• FastAPI
• SSE Client