crafty-mcp
This server provides an MCP interface for Crafty Controller 4, enabling AI assistants to manage Minecraft servers and the Crafty panel via natural language.
Authentication & Meta: Login with username/password (optional TOTP), get API info, list JSON schemas.
Host System: Retrieve host stats (CPU, RAM, disk, boot time); get and update Crafty panel configuration.
Server Management: List, get, create, update, delete Minecraft servers (Java, Bedrock, custom).
Runtime Control: Start, stop, restart, kill, backup, update executable, clone servers.
Monitoring: Get live stats (CPU/RAM, players, world, version, running state), console logs, historical stats.
Console Commands: Send commands to a server console (e.g., say, op, whitelist, gamemode).
File Management: List, read, write, create, delete, rename/move, decompress files/directories.
Backups: List, configure, trigger, restore, delete backups.
Scheduled Tasks: List, get, create, update, delete, manually run interval/cron tasks.
Webhooks: Manage and test webhooks (e.g., Discord) with triggers for server events.
User Administration: Manage users, permissions, API keys.
Role Management: List, get, create, update, delete roles.
Enables the creation and management of webhooks to send Minecraft server notifications, such as startup alerts and event triggers, to Discord channels.
crafty-mcp
An MCP (Model Context Protocol) server for Crafty Controller 4 — manage your Minecraft servers via AI assistants.
The first MCP server for Crafty Controller.
What it does
crafty-mcp exposes the full Crafty Controller 4 API V2 as MCP tools, letting AI assistants like Claude manage your Minecraft servers using natural language. Start and stop servers, send console commands, manage players, edit server files, configure backups, set up scheduled tasks, manage webhooks, and administer users — all without leaving your AI chat.
Related MCP server: mcp-server-docker
Quick Start
Add to your MCP client config:
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"crafty": {
"command": "npx",
"args": ["-y", "crafty-mcp"],
"env": {
"CRAFTY_URL": "https://localhost:8443",
"CRAFTY_API_TOKEN": "your-bearer-token",
"CRAFTY_ALLOW_INSECURE": "true"
}
}
}
}Claude Code:
claude mcp add crafty npx -y crafty-mcp \
--env CRAFTY_URL=https://localhost:8443 \
--env CRAFTY_API_TOKEN=your-token \
--env CRAFTY_ALLOW_INSECURE=trueCursor (.cursor/mcp.json):
{
"mcpServers": {
"crafty": {
"command": "npx",
"args": ["-y", "crafty-mcp"],
"env": {
"CRAFTY_URL": "https://localhost:8443",
"CRAFTY_API_TOKEN": "your-bearer-token",
"CRAFTY_ALLOW_INSECURE": "true"
}
}
}
}Configuration
Variable | Required | Description |
| Yes | Crafty Controller base URL (e.g. |
| No* | Bearer token from Crafty UI |
| No | Set to |
| No | Request timeout in milliseconds (default: |
*
CRAFTY_API_TOKENis optional if you authenticate dynamically using thecrafty_logintool, but recommended for most setups.
Getting your API token
Open Crafty Controller in your browser
Click your username -> Profile
Scroll to API Keys section
Click Generate Key
Copy the token and use it as
CRAFTY_API_TOKEN
A superuser token has full access to all servers and operations.
Available Tools
Auth / Meta
Tool | Description |
| Login with username/password to get a bearer token |
| Get API version info and MOTD |
| List available JSON schema names |
| Get a specific JSON schema by name |
Crafty Host (System)
Tool | Description |
| Get host CPU, RAM, disk, and boot time |
| Get Crafty panel configuration |
| Update Crafty panel configuration |
Servers — CRUD & Info
Tool | Description |
| List all managed Minecraft servers |
| Get a server's full configuration |
| Create a new Minecraft server (Java, Bedrock, custom) |
| Update server configuration |
| Permanently delete a server |
Servers — Runtime & Logs
Tool | Description |
| Get live stats: CPU/RAM, players online, version, world |
| Get server console log lines |
| Get historical stats for graphing |
Servers — Actions
Tool | Description |
| Start a server |
| Stop a server |
| Restart a server |
| Force-kill a server process |
| Trigger an immediate backup |
| Update the server jar/executable |
| Clone an existing server |
Servers — Console
Tool | Description |
| Send a command to the server console |
Servers — Files
Tool | Description |
| List files/directories in a server directory |
| Read a file's contents |
| Write or update a file |
| Delete files or directories |
| Create a new file |
| Create a new directory |
| Rename or move a file |
| Decompress an archive |
Servers — Backups
Tool | Description |
| List all backups with timestamps and sizes |
| Get backup configuration |
| Update backup settings |
| Restore a specific backup |
| Delete a backup |
Servers — Scheduled Tasks
Tool | Description |
| List all scheduled tasks |
| Get a task's configuration |
| Create a scheduled task (interval or cron) |
| Update a scheduled task |
| Delete a scheduled task |
| Manually trigger a task |
Servers — Webhooks
Tool | Description |
| List all webhooks |
| Get a webhook's details |
| Create a webhook (Discord, etc.) |
| Update a webhook |
| Delete a webhook |
| Send a test webhook message |
Users
Tool | Description |
| List all Crafty users |
| Get a user's details (use |
| Create a new user |
| Update a user |
| Delete a user |
| Get user permissions |
| Update user permissions |
| List a user's API keys |
| Generate a new API key |
| Revoke an API key |
Roles
Tool | Description |
| List all roles |
| Get a role's details |
| Create a new role |
| Update a role |
| Delete a role |
Examples
"What servers are running?" -> server_list + server_get_stats
"Start my SMP server" -> server_start
"How many players are online on survival?" -> server_get_stats
"Send 'say Server restarting in 5 minutes' to all servers" -> server_list + server_send_command
"Back up all servers" -> server_list + server_backup (for each)
"Show me the server.properties for my SMP server" -> server_get_file
"Create a Paper 1.21.4 server on port 25566" -> server_create
"Set up a daily backup at 3 AM" -> server_create_task (cron: "0 3 * * *")
"Add a Discord webhook that fires when the server starts" -> server_create_webhook
"Op PlayerName on the survival server" -> server_send_commandDevelopment
git clone https://github.com/HadiCherkaoui/crafty-mcp.git
cd crafty-mcp
npm install
npm run build
# Test locally
CRAFTY_URL=https://localhost:8443 \
CRAFTY_API_TOKEN=your-token \
CRAFTY_ALLOW_INSECURE=true \
node dist/index.js
# Inspect with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.jsLicense
AGPL-3.0-or-later — Copyright (C) 2026 Hadi Cherkaoui. See LICENSE.
Available Tools
63 toolscrafty_api_infoA
Get Crafty Controller API version information and message of the day (MOTD). Does not require authentication.
Inputs: no named parameters.
crafty_get_configB
Get Crafty Controller panel configuration settings
Inputs: no named parameters.
crafty_get_schemaA
Get a specific JSON schema by name from Crafty Controller. Use crafty_list_schemas to discover available schema names.
Inputs: schema_name (required).
crafty_get_statsB
Get Crafty Controller host system stats: CPU usage/count/frequency, RAM usage/total/percent, disk data (device, total, used, free, percent, filesystem, mount), and boot time
Inputs: no named parameters.
crafty_list_schemasA
List all available JSON schema names in Crafty Controller. Does not require authentication.
Inputs: no named parameters.
crafty_loginA
Login with username and password to get a bearer token. Use this if you prefer username/password authentication over a pre-generated API token.
Inputs: username (required), password (required), totp.
crafty_update_configC
Update Crafty Controller panel configuration settings
Inputs: config (required).
role_createC
Create a new role in Crafty Controller
Inputs: role_data (required).
role_deleteC
Delete a role from Crafty Controller
Inputs: role_id (required).
role_getB
Get details for a specific role
Inputs: role_id (required).
role_listB
List all roles in Crafty Controller
Inputs: no named parameters.
role_updateC
Update an existing role in Crafty Controller
Inputs: role_id (required), updates (required).
server_backupB
Trigger an immediate backup of a Minecraft server's files
Inputs: server_id (required).
server_cloneB
Clone an existing Minecraft server (server must not be running)
Inputs: server_id (required).
server_createC
Create a new Minecraft server in Crafty Controller. Supports Java (download jar or import), Bedrock, and custom server types.
Inputs: name (required), monitoring_type (required), create_type (required), minecraft_java_create_data, +1 more.
server_create_directoryC
Create a new directory on a Minecraft server
Inputs: server_id (required), parent (required), name (required).
server_create_fileC
Create a new file on a Minecraft server
Inputs: server_id (required), parent (required), name (required).
server_create_taskA
Create a scheduled task for a Minecraft server. Use interval_type with interval for simple schedules (e.g., every 6 hours), or set cron_string with empty interval_type for cron-based schedules (e.g., '0 3 * * *' for 3 AM daily).
Inputs: server_id (required), name (required), action (required), enabled, +8 more.
server_create_webhookC
Create a new webhook for a Minecraft server. Supports Discord and other webhook types. Trigger events: server_start, server_stop, server_backup, player_join, player_leave, etc.
Inputs: server_id (required), webhook_type (required), name (required), url (required), +4 more.
server_decompress_fileC
Decompress/unzip an archive file on a Minecraft server
Inputs: server_id (required), folder (required).
server_deleteC
Delete a Minecraft server from Crafty Controller
Inputs: server_id (required).
server_delete_backupC
Delete a specific backup for a Minecraft server
Inputs: server_id (required), backup_id (required).
server_delete_fileC
Delete one or more files or directories from a Minecraft server
Inputs: server_id (required), paths (required).
server_delete_taskC
Delete a scheduled task from a Minecraft server
Inputs: server_id (required), task_id (required).
server_delete_webhookC
Delete a webhook from a Minecraft server
Inputs: server_id (required), webhook_id (required).
server_getC
Get full configuration details for a specific Minecraft server
Inputs: server_id (required).
server_get_backup_configB
Get backup configuration for a Minecraft server (compression, exclusions, schedule, max backups)
Inputs: server_id (required).
server_get_fileB
Read the contents of a file on a Minecraft server (e.g., server.properties, ops.json, whitelist.json)
Inputs: server_id (required), path (required).
server_get_historyA
Get historical runtime statistics for a Minecraft server (CPU, RAM over time, useful for graphing trends)
Inputs: server_id (required).
server_get_logsC
Get a Minecraft server's console logs as an array of log lines
Inputs: server_id (required).
server_get_statsA
Get live runtime statistics for a Minecraft server including CPU/RAM usage, online player count and list, world name/size, MOTD, version, and whether it is running
Inputs: server_id (required).
server_get_taskB
Get configuration for a specific scheduled task
Inputs: server_id (required), task_id (required).
server_get_webhookC
Get details for a specific webhook
Inputs: server_id (required), webhook_id (required).
server_killB
Force-kill a Minecraft server process immediately
Inputs: server_id (required).
server_listA
List all Minecraft servers managed by Crafty Controller with their IDs, names, types, ports, and configurations
Inputs: no named parameters.
server_list_backupsB
List all backups for a Minecraft server with timestamps and sizes
Inputs: server_id (required).
server_list_filesB
List files and directories in a Minecraft server's directory
Inputs: server_id (required), path.
server_list_tasksB
List all scheduled tasks for a Minecraft server
Inputs: server_id (required).
server_list_webhooksC
List all webhooks configured for a Minecraft server
Inputs: server_id (required).
server_rename_fileC
Rename or move a file or directory on a Minecraft server
Inputs: server_id (required), path (required), new_name (required).
server_restartC
Restart a Minecraft server
Inputs: server_id (required).
server_restore_backupC
Restore a specific backup for a Minecraft server
Inputs: server_id (required), backup_id (required), filename (required), in_place.
server_run_taskC
Manually trigger a scheduled task immediately
Inputs: server_id (required), task_id (required).
server_send_commandA
Send a command to a running Minecraft server's console. Examples: 'say Hello everyone!', 'op PlayerName', 'whitelist add Player', 'gamemode creative Player', 'time set day', 'weather clear'
Inputs: server_id (required), command (required).
server_startC
Start a Minecraft server
Inputs: server_id (required).
server_stopA
Stop a Minecraft server (sends configured stop command)
Inputs: server_id (required).
server_test_webhookC
Send a test message to verify a webhook is working
Inputs: server_id (required), webhook_id (required).
server_updateC
Update a Minecraft server's configuration (name, ports, auto-start, crash detection, stop command, etc.)
Inputs: server_id (required), updates (required).
server_update_backup_configC
Update backup configuration for a Minecraft server
Inputs: server_id (required), backup_name, max_backups, compress, +4 more.
server_update_executableC
Update the server jar/executable from the configured download URL
Inputs: server_id (required).
server_update_fileC
Write or update a file on the Minecraft server (e.g., server.properties, ops.json, whitelist.json)
Inputs: server_id (required), path (required), contents (required), overwrite.
server_update_taskC
Update an existing scheduled task for a Minecraft server
Inputs: server_id (required), task_id (required), updates (required).
server_update_webhookC
Update an existing webhook for a Minecraft server
Inputs: server_id (required), webhook_id (required), updates (required).
user_createA
Create a new Crafty Controller user account. Requires superuser privileges.
Inputs: username (required), password (required), email, lang, +3 more.
user_create_api_keyC
Generate a new API key for a Crafty Controller user
Inputs: user_id (required), name.
user_deleteA
Permanently delete a Crafty Controller user account. Requires superuser privileges.
Inputs: user_id (required).
user_delete_api_keyC
Revoke/delete an API key for a Crafty Controller user
Inputs: user_id (required), key_id (required).
user_getA
Get details for a specific Crafty Controller user. Use '@me' as user_id to get the currently authenticated user.
Inputs: user_id (required).
user_get_api_keysC
List API keys for a Crafty Controller user
Inputs: user_id (required).
user_get_permissionsC
Get a user's Crafty and per-server permissions
Inputs: user_id (required).
user_listB
List all Crafty Controller users. Returns user_id, username, enabled, superuser, lang, and creation date.
Inputs: ids_only.
user_updateC
Update a Crafty Controller user account
Inputs: user_id (required), updates (required).
user_update_permissionsC
Update a user's Crafty and per-server permissions
Inputs: user_id (required), permissions (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 63 tools
Most tools have distinct purposes, but some overlap exists within server file management (e.g., server_create_file, server_update_file, server_get_file) and webhook/task operations, which could cause minor confusion. However, descriptions clarify specific actions, and the overall organization into categories (crafty_, role_, server_, user_) helps disambiguation.
Tool names follow a highly consistent pattern: all use snake_case with a clear prefix (crafty_, role_, server_, user_) followed by a verb_noun structure (e.g., server_create, user_update). This consistency makes the set predictable and easy to navigate, with no deviations in style.
With 63 tools, the count is excessive for an MCP server, making it overwhelming and likely to cause agent confusion. While the domain (Minecraft server management) is broad, this many tools suggests over-fragmentation, such as separate tools for each file operation, rather than a more consolidated approach.
The tool set provides comprehensive coverage for Crafty Controller and Minecraft server management, including CRUD operations for servers, roles, users, and related entities (e.g., backups, tasks, webhooks). It supports full lifecycle management with no obvious gaps, from server creation to monitoring and maintenance.
Related MCP Connectors
Related MCP Servers
- MIT
- MIT
- AlicenseAqualityBmaintenanceMCP Server for ChainAnalyzer(https://chain-analyzer.com)6156 npm1MIT
- MIT