Skip to main content
Glama

crafty-mcp

npm

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

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

  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

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/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

AGPL-3.0-or-later — Copyright (C) 2026 Hadi Cherkaoui. See LICENSE.

Available Tools

63 tools
crafty_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

    B3.4/5.0

    Scored across 63 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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