ZimaOS MCP服务器
用于与ZimaOS文件系统和存储交互的模型上下文协议（MCP）服务器。此服务器允许您通过Cursor或其他MCP兼容客户端读取、写入、搜索和管理ZimaOS设备上的文件。
特性
文件管理
- 📁 列出目录 -浏览ZimaOS上的文件和文件夹
- 📄 读取文件 -从ZimaOS读取文件内容
- ✏️ 写入/编辑文件 -在ZimaOS上创建和修改文件
- 🔍 搜索文件 -按名称或内容搜索文件
- 📊 获取文件信息 -检索有关文件和目录的详细元数据
- 📂 创建目录 -创建新的目录结构
- 🗂️ 列出允许的目录 -查看可访问的存储位置
Docker容器管理
- 🐳 列出Docker容器 -查看部署在ZimaOS上的所有Docker容器
- ▶️ 启动容器 -启动已停止的Docker容器
- ⏹️ 停止集装箱 -停止运行Docker容器
- 🔄 重新启动容器 -重启Docker容器
- 📋 查看容器日志 -从Docker容器获取日志
- ℹ️ 获取容器信息 -检索有关容器的详细信息
先决条件
- 已安装Node.js 18+
- 访问启用API的ZimaOS设备
- ZimaOS API令牌（从ZimaOS管理面板获取）
安装
选项1：从GitHub安装（推荐）
- 克隆或下载此存储库：
git clone https://github.com/bobdivx/zimaos-cursor-mcp.git
cd zimaos-cursor-mcp- 安装依赖项：
npm install- 构建项目：
npm run build- 复制示例环境文件：
cp .env.example .env- 编辑
.env并添加您的ZimaOS配置：
ZIMAOS_API_BASE=http://your-zimaos-host.local
ZIMAOS_API_TOKEN=your-api-token-here选项2：直接与游标MCP配置一起使用
您可以将Cursor配置为直接使用此服务器，而无需全局安装：
配置
光标MCP配置
将以下内容添加到您的Cursor MCP配置文件中（通常位于 ~/.cursor/mcp.json 在macOS/Linux或 C:\Users\\.cursor\mcp.json 在Windows上）：
{
"mcpServers": {
"zimaos": {
"command": "node",
"args": ["/dist/index.js"],
"env": {
"ZIMAOS_API_BASE": "http://your-zimaos-host.local",
"ZIMAOS_API_TOKEN": "your-api-token-here"
}
}
}
}重要提示： 替换 `` 使用系统上此存储库的实际路径。
环境变量
文件操作所需：
ZIMAOS_API_BASE（必需）：ZimaOS API的基本URL（例如。，http://zimacube.local或http://192.168.1.100)ZIMAOS_API_TOKEN（必需）：您的ZimaOS API令牌（从ZimaOS管理面板获取）
Docker管理（SSH）所需：
ZIMAOS_SSH_PASSWORD（必填）：ZimaOS系统的SSH密码ZIMAOS_SSH_HOST（可选）：SSH主机名。如果未提供，将自动检测ZIMAOS_API_BASEZIMAOS_SSH_USERNAME（可选）：SSH用户名，默认为zimaosZIMAOS_SSH_PORT（可选）：SSH端口，默认为22
注： 如果 ZIMAOS_SSH_HOST 未设置，将自动从中提取 ZIMAOS_API_BASE （例如。， http://zimacube.local:90 → zimacube.local)
获取ZimaOS API代币
- 访问ZimaOS管理面板
- 导航到API设置或开发人员部分
- 生成或复制您的API令牌
- 在配置中使用此令牌
用法
配置后，MCP服务器将在Cursor中自动可用。您可以使用它来：
- 让Cursor列出ZimaOS上某个目录中的文件
- 从ZimaOS读取文件
- 在ZimaOS上创建或编辑文件
- 按名称或内容搜索文件
- 获取有关文件和目录的信息
您可以对Cursor进行的示例查询：
文件操作：
- “列出ZimaOS上/Documents中的所有文件”
- “从ZimaOS读取/path/to/file.txt的内容”
- “在我的ZimaOS上搜索包含‘项目’的文件”
Docker操作：
- “列出ZimaOS上的所有Docker容器”
- “启动名为'myapp'的Docker容器”
- “显示容器'nginx'的日志”
- 获取容器“数据库”的相关信息
- “重新启动ID为abc123的容器”
发展
建设项目
npm run build以开发模式运行
npm run dev这将编译TypeScript并启动服务器。
项目结构
zimaos-cursor-mcp/
├── src/
│ ├── index.ts # Main server entry point
│ ├── lib/
│ │ └── getAxios.ts # API client configuration (File, Docker, Storage APIs)
│ ├── tools/ # MCP tools (file and Docker operations)
│ │ ├── *.ts # File management tools
│ │ ├── ListDockerContainersTool.ts
│ │ ├── StartDockerContainerTool.ts
│ │ ├── StopDockerContainerTool.ts
│ │ ├── RestartDockerContainerTool.ts
│ │ ├── GetDockerContainerLogsTool.ts
│ │ └── GetDockerContainerInfoTool.ts
│ ├── resources/ # MCP resources
│ └── prompts/ # MCP prompts
├── dist/ # Compiled JavaScript (generated)
├── .env.example # Example environment configuration
└── package.json故障排除
服务器无法启动
- 核实一下
ZIMAOS_API_BASE和ZIMAOS_API_TOKEN设置正确 - 确保您的ZimaOS设备可以从您的机器访问
- 检查您的ZimaOS设备上是否启用了API
工具未加载
- 确保你已经跑过了
npm run build编译TypeScript - 验证
dist/目录包含已编译的文件 - 检查所有依赖项是否已安装
npm install
连接错误
- 验证
ZIMAOS_API_BASEURL正确且可访问 - 检查您与ZimaOS设备的网络连接
- 确保API令牌有效且未过期
安全须知
⚠️ 重要安全提示：
- 永远不要承诺你的
.env文件 -它包含敏感凭据 - 这
.env文件已在.gitignore防止意外犯罪 - 始终使用
.env.example作为模板 - 保持API代币的安全，并在受到威胁时对其进行轮换
- 仅在确保没有提交敏感数据后共享您的存储库
发布到GitHub
如果要发布此存储库：
- 在GitHub上创建一个名为的新存储库
zimaos-cursor-mcp
- 初始化git（如果尚未完成）：
git init
git add .
git commit -m "Initial commit: ZimaOS MCP Server"- 将您的GitHub存储库添加为远程：
git remote add origin https://github.com/bobdivx/zimaos-cursor-mcp.git
git branch -M main
git push -u origin main- 推之前，请仔细检查：
- 不 .env 文件已包含（检查 .gitignore) - 任何文件中都没有硬编码凭据 - 删除所有敏感信息
贡献
欢迎投稿！请随时提交拉取请求。
- 分叉存储库
- 创建功能分支(
git checkout -b feature/amazing-feature) - 提交您的更改(
git commit -m 'Add some amazing feature') - 推到分支(
git push origin feature/amazing-feature) - 打开拉取请求
许可证
\[在此处添加您的许可证-考虑MIT、Apache 2.0或其他合适的许可证\]
支持
有关问题和疑问，请在GitHub存储库上打开问题：https://github.com/bobdivx/zimaos-cursor-mcp/issues