内容
# crafty-mcp
适用于 [Crafty Controller 4](https://craftycontrol.com) 的MCP（模型上下文协议）服务器 - 通过AI助手管理您的Minecraft服务器。
> 适用于Crafty Controller的首个MCP服务器。
## 功能描述
`crafty-mcp` 将完整的Crafty Controller 4 API V2作为MCP工具公开，让Claude等AI助手可以使用自然语言管理您的Minecraft服务器。启动和停止服务器、发送控制台命令、管理玩家、编辑服务器文件、配置备份、设置计划任务、管理Webhook以及管理用户 - 所有操作都无需离开您的AI聊天。
## 快速入门
将以下内容添加到您的MCP客户端配置中：
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上， `%APPDATA%\Claude\claude_desktop_config.json` 在Windows上):
```json
{
"mcpServers": {
"crafty": {
"command": "npx",
"args": ["-y", "crafty-mcp"],
"env": {
"CRAFTY_URL": "https://localhost:8443",
"CRAFTY_API_TOKEN": "您的Bearer令牌",
"CRAFTY_ALLOW_INSECURE": "true"
}
}
}
}
```
**Claude Code:**
```bash
claude mcp add crafty npx -y crafty-mcp \
--env CRAFTY_URL=https://localhost:8443 \
--env CRAFTY_API_TOKEN=您的令牌 \
--env CRAFTY_ALLOW_INSECURE=true
```
**Cursor** (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"crafty": {
"command": "npx",
"args": ["-y", "crafty-mcp"],
"env": {
"CRAFTY_URL": "https://localhost:8443",
"CRAFTY_API_TOKEN": "您的Bearer令牌",
"CRAFTY_ALLOW_INSECURE": "true"
}
}
}
}
```
## 配置
| 变量 | 是否必需 | 描述 |
| --- | --- | --- |
| `CRAFTY_URL` | 是 | Crafty Controller基准URL（例如 `https://localhost:8443`） |
| `CRAFTY_API_TOKEN` | 否* | 来自Crafty UI的Bearer令牌 |
| `CRAFTY_ALLOW_INSECURE` | 否 | 设置为 `true` 以允许自签名证书（Crafty的默认值） |
| `CRAFTY_TIMEOUT` | 否 | 请求超时（毫秒）（默认值：`30000`） |
> *如果您使用 `crafty_login` 工具动态认证，则 `CRAFTY_API_TOKEN` 是可选的，但建议大多数设置使用。
## 获取API令牌
1. 在浏览器中打开Crafty Controller
2. 点击您的用户名 -> **个人资料**
3. 滚动到 **API密钥** 部分
4. 点击 **生成密钥**
5. 复制令牌并将其用作 `CRAFTY_API_TOKEN`
> 超级用户令牌对所有服务器和操作具有完全访问权限。
## 可用工具
### 认证 / 元数据
| 工具 | 描述 |
| --- | --- |
| `crafty_login` | 使用用户名/密码登录以获取Bearer令牌 |
| `crafty_api_info` | 获取API版本信息和MOTD |
| `crafty_list_schemas` | 列出可用的JSON模式名称 |
| `crafty_get_schema` | 获取特定JSON模式 |
### Crafty主机（系统）
| 工具 | 描述 |
| --- | --- |
| `crafty_get_stats` | 获取主机CPU、RAM、磁盘和启动时间 |
| `crafty_get_config` | 获取Crafty面板配置 |
| `crafty_update_config` | 更新Crafty面板配置 |
### 服务器 - CRUD 和信息
| 工具 | 描述 |
| --- | --- |
| `server_list` | 列出所有受管理的Minecraft服务器 |
| `server_get` | 获取服务器的完整配置 |
| `server_create` | 创建新的Minecraft服务器（Java、Bedrock、自定义） |
| `server_update` | 更新服务器配置 |
| `server_delete` | 永久删除服务器 |
### 服务器 - 运行时和日志
| 工具 | 描述 |
| --- | --- |
| `server_get_stats` | 获取实时统计数据：CPU/RAM、在线玩家、版本、世界 |
| `server_get_logs` | 获取服务器控制台日志行 |
| `server_get_history` | 获取历史统计数据以进行绘图 |
### 服务器 - 操作
| 工具 | 描述 |
| --- | --- |
| `server_start` | 启动服务器 |
| `server_stop` | 停止服务器 |
| `server_restart` | 重启服务器 |
| `server_kill` | 强制终止服务器进程 |
| `server_backup` | 触发立即备份 |
| `server_update_executable` | 更新服务器jar/可执行文件 |
| `server_clone` | 克隆现有服务器 |
### 服务器 - 控制台
| 工具 | 描述 |
| --- | --- |
| `server_send_command` | 向服务器控制台发送命令 |
### 服务器 - 文件
| 工具 | 描述 |
| --- | --- |
| `server_list_files` | 列出服务器目录中的文件/目录 |
| `server_get_file` | 读取文件内容 |
| `server_update_file` | 写入或更新文件 |
| `server_delete_file` | 删除文件或目录 |
| `server_create_file` | 创建新文件 |
| `server_create_directory` | 创建新目录 |
| `server_rename_file` | 重命名或移动文件 |
| `server_decompress_file` | 解压存档 |
### 服务器 - 备份
| 工具 | 描述 |
| --- | --- |
| `server_list_backups` | 列出所有备份，附带时间戳和大小 |
| `server_get_backup_config` | 获取备份配置 |
| `server_update_backup_config` | 更新备份设置 |
| `server_restore_backup` | 恢复特定备份 |
| `server_delete_backup` | 删除备份 |
### 服务器 - 计划任务
| 工具 | 描述 |
| --- | --- |
| `server_list_tasks` | 列出所有计划任务 |
| `server_get_task` | 获取任务配置 |
| `server_create_task` | 创建计划任务（间隔或cron） |
| `server_update_task` | 更新计划任务 |
| `server_delete_task` | 删除计划任务 |
| `server_run_task` | 手动触发任务 |
### 服务器 - Webhook
| 工具 | 描述 |
| --- | --- |
| `server_list_webhooks` | 列出所有Webhook |
| `server_get_webhook` | 获取Webhook的详细信息 |
| `server_create_webhook` | 创建Webhook（Discord等） |
| `server_update_webhook` | 更新Webhook |
| `server_delete_webhook` | 删除Webhook |
| `server_test_webhook` | 发送测试Webhook消息 |
### 用户
| 工具 | 描述 |
| --- | --- |
| `user_list` | 列出所有Crafty用户 |
| `user_get` | 获取用户详细信息（使用 `@me` 获取您自己） |
| `user_create` | 创建新用户 |
| `user_update` | 更新用户 |
| `user_delete` | 删除用户 |
| `user_get_permissions` | 获取用户权限 |
| `user_update_permissions` | 更新用户权限 |
| `user_get_api_keys` | 列出用户的API密钥 |
| `user_create_api_key` | 生成新的API密钥 |
| `user_delete_api_key` | 撤销API密钥 |
### 角色
| 工具 | 描述 |
| --- | --- |
| `role_list` | 列出所有角色 |
| `role_get` | 获取角色详细信息 |
| `role_create` | 创建新角色 |
| `role_update` | 更新角色 |
| `role_delete` | 删除角色 |
## 示例
```
"哪些服务器正在运行？" -> server_list + server_get_stats
"启动我的SMP服务器" -> server_start
"生存服务器有多少玩家在线？" -> server_get_stats
"向所有服务器发送 'say Server restarting in 5 minutes' 消息" -> server_list + server_send_command
"备份所有服务器" -> server_list + server_backup （每个服务器）
"显示我的SMP服务器的server.properties文件" -> server_get_file
"创建一个Paper 1.21.4服务器，端口为25566" -> server_create
"设置每天凌晨3点备份" -> server_create_task （cron: "0 3 * * *"）
"添加一个服务器启动时触发的Discord Webhook" -> server_create_webhook
"在生存服务器上对PlayerName赋予管理员权限" -> server_send_command
```
## 开发
```bash
git clone https://github.com/HadiCherkaoui/crafty-mcp.git
cd crafty-mcp
npm install
npm run build
# 在本地测试
CRAFTY_URL=https://localhost:8443 \
CRAFTY_API_TOKEN=您的令牌 \
CRAFTY_ALLOW_INSECURE=true \
node dist/index.js
# 使用MCP Inspector检查
npx @modelcontextprotocol/inspector node dist/index.js
```
## 许可证
GPLv3 — [Hadi Cherkaoui](https://github.com/HadiCherkaoui)
