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, originally built by Hadi Cherkaoui.

🍴 This is a maintained fork. Upstream: HadiCherkaoui/crafty-mcp (also mirrored at GitLab). This fork exists to fix a response-formatting bug (below) that broke most mutating tools. A fix has been offered upstream — once merged, prefer the canonical npx crafty-mcp from npm again.

🎮 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.

🐛 What this fork fixes

Every mutating tool call — server_start, server_stop, server_update, server_create_file, and 50+ others — built its success response as JSON.stringify(data, null, 2), where data came straight from the Crafty API's JSON envelope. Most of Crafty's action endpoints respond with just {"status":"ok"} and no data key on success. JSON.stringify(undefined, ...) isn't a string — it's the literal JavaScript value undefined — so the MCP SDK's own result-schema validation rejected it, and every one of those calls failed with a client-visible -32602 Invalid tools/call result error, even though the underlying Crafty action had actually succeeded.

⚠️ Real-world impact: this silently broke server_start/stop/restart/kill, every file-write tool, and most server_update/user_update/etc. calls — discovered while debugging a Minecraft server that Crafty reported as "not starting," when in fact it was starting fine and only the tool call was failing.

The fix (src/tools/response.ts) centralizes response formatting behind two helpers, toolSuccess/toolError, replacing 57 duplicated call sites across 11 files. While fixing it, the pipeline's own adversarial review caught a second, more serious issue it would have introduced: CraftyClient.request() never checked the HTTP status, only an exact {"status":"error"} JSON envelope — so an HTTP 401/403/500 with a different error shape would resolve as success too, meaning destructive tools (server_delete, user_delete, server_delete_backup, …) could report success on a denied or failed request. Both are fixed and covered by regression tests (171 tests total, up from 28).

See CHANGES.md for the full commit-level breakdown.

🚀 Quick Start

Until the fix is merged upstream, install from this fork rather than the npm package (which still has the bug):

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", "github:Jemplayer82/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 github:Jemplayer82/crafty-mcp \
  --env CRAFTY_URL=https://localhost:8443 \
  --env CRAFTY_API_TOKEN=your-token \
  --env CRAFTY_ALLOW_INSECURE=true

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "crafty": {
      "command": "npx",
      "args": ["-y", "github:Jemplayer82/crafty-mcp"],
      "env": {
        "CRAFTY_URL": "https://localhost:8443",
        "CRAFTY_API_TOKEN": "your-bearer-token",
        "CRAFTY_ALLOW_INSECURE": "true"
      }
    }
  }
}

Or build and run locally (see 🛠 Development) and point command/args at node and dist/index.js.

⚙️ Configuration

Variable	Required	Description
`CRAFTY_URL`	Yes	Crafty Controller base URL (e.g. `https://localhost:8443`)
`CRAFTY_API_TOKEN`	No*	Bearer token from Crafty UI
`CRAFTY_ALLOW_INSECURE`	No	Set to `true` to allow self-signed certificates (Crafty's default)
`CRAFTY_TIMEOUT`	No	Request timeout in milliseconds (default: `30000`)

*CRAFTY_API_TOKEN is optional if you authenticate dynamically using the crafty_login tool, 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
`crafty_login`	Login with username/password to get a bearer token
`crafty_api_info`	Get API version info and MOTD
`crafty_list_schemas`	List available JSON schema names
`crafty_get_schema`	Get a specific JSON schema by name

Crafty Host (System)

Tool	Description
`crafty_get_stats`	Get host CPU, RAM, disk, and boot time
`crafty_get_config`	Get Crafty panel configuration
`crafty_update_config`	Update Crafty panel configuration

Servers — CRUD & Info

Tool	Description
`server_list`	List all managed Minecraft servers
`server_get`	Get a server's full configuration
`server_create`	Create a new Minecraft server (Java, Bedrock, custom)
`server_update`	Update server configuration
`server_delete`	Permanently delete a server

Servers — Runtime & Logs

Tool	Description
`server_get_stats`	Get live stats: CPU/RAM, players online, version, world
`server_get_logs`	Get server console log lines
`server_get_history`	Get historical stats for graphing

Servers — Actions

Tool	Description
`server_start`	Start a server
`server_stop`	Stop a server
`server_restart`	Restart a server
`server_kill`	Force-kill a server process
`server_backup`	Trigger an immediate backup
`server_update_executable`	Update the server jar/executable
`server_clone`	Clone an existing server

Servers — Console

Tool	Description
`server_send_command`	Send a command to the server console

Servers — Files

Tool	Description
`server_list_files`	List files/directories in a server directory
`server_get_file`	Read a file's contents
`server_update_file`	Write or update a file
`server_delete_file`	Delete files or directories
`server_create_file`	Create a new file
`server_create_directory`	Create a new directory
`server_rename_file`	Rename or move a file
`server_decompress_file`	Decompress an archive

Servers — Backups

Tool	Description
`server_list_backups`	List all backups with timestamps and sizes
`server_get_backup_config`	Get backup configuration
`server_update_backup_config`	Update backup settings
`server_restore_backup`	Restore a specific backup
`server_delete_backup`	Delete a backup

Servers — Scheduled Tasks

Tool	Description
`server_list_tasks`	List all scheduled tasks
`server_get_task`	Get a task's configuration
`server_create_task`	Create a scheduled task (interval or cron)
`server_update_task`	Update a scheduled task
`server_delete_task`	Delete a scheduled task
`server_run_task`	Manually trigger a task

Servers — Webhooks

Tool	Description
`server_list_webhooks`	List all webhooks
`server_get_webhook`	Get a webhook's details
`server_create_webhook`	Create a webhook (Discord, etc.)
`server_update_webhook`	Update a webhook
`server_delete_webhook`	Delete a webhook
`server_test_webhook`	Send a test webhook message

Users

Tool	Description
`user_list`	List all Crafty users
`user_get`	Get a user's details (use `@me` for yourself)
`user_create`	Create a new user
`user_update`	Update a user
`user_delete`	Delete a user
`user_get_permissions`	Get user permissions
`user_update_permissions`	Update user permissions
`user_get_api_keys`	List a user's API keys
`user_create_api_key`	Generate a new API key
`user_delete_api_key`	Revoke an API key

Roles

Tool	Description
`role_list`	List all roles
`role_get`	Get a role's details
`role_create`	Create a new role
`role_update`	Update a role
`role_delete`	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_command

🛠 Development

git clone https://github.com/Jemplayer82/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.js

# Run the test suite
npm test              # unit tests (171 tests, no external dependencies)
npm run test:integration   # needs Docker + a live Crafty instance, not run in CI here

🙏 Credits

Hadi Cherkaoui — original author of crafty-mcp and all 63 MCP tools. This fork is a bugfix on his work, not a rewrite.
The response-formatting fix and its regression suite were built with dev-pipeline — Claude plans and adversarially reviews, Kimi K2 writes the code. Every commit carries an Authored-By-Model trailer; see CHANGES.md.

Name		Name	Last commit message	Last commit date
LICENSES		LICENSES
assets		assets
src		src
tests		tests
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
CHANGES.md		CHANGES.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
REUSE.toml		REUSE.toml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.tests.json		tsconfig.tests.json
vitest.config.ts		vitest.config.ts
vitest.integration.config.ts		vitest.integration.config.ts

Navigation Menu

Repository files navigation

crafty-mcp

🎮 What it does

🐛 What this fork fixes

🚀 Quick Start

⚙️ Configuration

🔐 Getting your API token

📚 Available Tools

Auth / Meta

Crafty Host (System)

Servers — CRUD & Info

Servers — Runtime & Logs

Servers — Actions

Servers — Console

Servers — Files

Servers — Backups

Servers — Scheduled Tasks

Servers — Webhooks

Users

Roles

💡 Examples

🛠 Development

🙏 Credits

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

crafty-mcp

🎮 What it does

🐛 What this fork fixes

🚀 Quick Start

⚙️ Configuration

🔐 Getting your API token

📚 Available Tools

Auth / Meta

Crafty Host (System)

Servers — CRUD & Info

Servers — Runtime & Logs

Servers — Actions

Servers — Console

Servers — Files

Servers — Backups

Servers — Scheduled Tasks

Servers — Webhooks

Users

Roles

💡 Examples

🛠 Development

🙏 Credits

📄 License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages