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.

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=true

Cursor (.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

*CRAFTY_API_TOKEN is optional if you authenticate dynamically using the crafty_login tool, but recommended for most setups.

Getting your API token

1. Open Crafty Controller in your browser
2. Click your username -> Profile
3. Scroll to API Keys section
4. Click Generate Key
5. 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

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

"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/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.js

License

GPLv3 — Hadi Cherkaoui