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安装(推荐)
- 克隆或下载此存储库:```bash
git clone https://github.com/bobdivx/zimaos-cursor-mcp.git
cd zimaos-cursor-mcp
1. 安装依赖项:```bash
npm install
- 构建项目:```bash
npm run build
1. 复制示例环境文件:```bash
cp .env.example .env
- 编辑
.env并添加您的ZimaOS配置:```env
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上):```json
{
"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的容器”
发展
建设项目```bash
npm run build
### 以开发模式运行```bash
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_BASE` URL正确且可访问
- 检查您与ZimaOS设备的网络连接
- 确保API令牌有效且未过期
## 安全须知
⚠️ **重要安全提示:**
- **永远不要承诺你的 `.env` 文件** -它包含敏感凭据
- 这 `.env` 文件已在 `.gitignore` 防止意外犯罪
- 始终使用 `.env.example` 作为模板
- 保持API代币的安全,并在受到威胁时对其进行轮换
- 仅在确保没有提交敏感数据后共享您的存储库
## 发布到GitHub
如果要发布此存储库:
1. 在GitHub上创建一个名为的新存储库 `zimaos-cursor-mcp`
1. 初始化git(如果尚未完成):```bash
git init
git add .
git commit -m "Initial commit: ZimaOS MCP Server"
-
将您的GitHub存储库添加为远程:
bash 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
