# minecraft-mcp

This MCP server enables AI agents to control a player character in Minecraft. It runs via JsMacros to execute JavaScript scripts, capture screenshots, and report status in-game.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 26 repo stars
- Author: MakkCH
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/MakkCH/minecraft_mcp
- Updated: 2026-11-13
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/minecraft-mcp

## What it does

The server exposes game functions as tools for an AI agent to interact with Minecraft. To get started, install the Fabric mod in your `mods/` folder alongside JsMacros and Baritone, then retrieve your token and port from the in-game settings screen opened by pressing F8.

The agent controls the character by writing and running JavaScript code, receiving outputs and visual feedback. You retain manual control at any time by typing `/mcp stop` in the game chat. Requirements include Fabric Loader 0.19.5 or later and Java 25 or higher.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `MINECRAFT_MCP_TOKEN`, `MINECRAFT_MCP_PORT`, `MINECRAFT_MCP_URL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env MINECRAFT_MCP_TOKEN=<MINECRAFT_MCP_TOKEN> --env MINECRAFT_MCP_PORT=<MINECRAFT_MCP_PORT> --env MINECRAFT_MCP_URL=<MINECRAFT_MCP_URL> --transport stdio minecraft-mcp -- npx -y @makkch/minecraft-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add minecraft-mcp --env MINECRAFT_MCP_TOKEN=<MINECRAFT_MCP_TOKEN> --env MINECRAFT_MCP_PORT=<MINECRAFT_MCP_PORT> --env MINECRAFT_MCP_URL=<MINECRAFT_MCP_URL> -- npx -y @makkch/minecraft-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "minecraft-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@makkch/minecraft-mcp"
            ],
            "env": {
                "MINECRAFT_MCP_TOKEN": "<MINECRAFT_MCP_TOKEN>",
                "MINECRAFT_MCP_PORT": "<MINECRAFT_MCP_PORT>",
                "MINECRAFT_MCP_URL": "<MINECRAFT_MCP_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "minecraft-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@makkch/minecraft-mcp"
            ],
            "env": {
                "MINECRAFT_MCP_TOKEN": "<MINECRAFT_MCP_TOKEN>",
                "MINECRAFT_MCP_PORT": "<MINECRAFT_MCP_PORT>",
                "MINECRAFT_MCP_URL": "<MINECRAFT_MCP_URL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MINECRAFT_MCP_TOKEN=<MINECRAFT_MCP_TOKEN> -e MINECRAFT_MCP_PORT=<MINECRAFT_MCP_PORT> -e MINECRAFT_MCP_URL=<MINECRAFT_MCP_URL> minecraft-mcp npx -y @makkch/minecraft-mcp
```
Replace <…> with your own values

## When to use it
- automate resource gathering in Minecraft
- build structures using AI-generated instructions
- navigate and explore game worlds autonomously

## Example prompts
- Build a stone workshop by the riverside
- Locate the nearest village and harvest resources
- Collect iron to craft tools

## Similar
- [minecraft-modding](https://affpapa.org/en/nevibecode/skills/minecraft-modding.md) — skill · 966 installs
- [minecraft-testing](https://affpapa.org/en/nevibecode/skills/minecraft-testing.md) — skill · 386 installs
- [Minecraft](https://affpapa.org/en/nevibecode/mcp/minecraft.md) — MCP server
- [minecraft-bukkit-pro](https://affpapa.org/en/nevibecode/skills/minecraft-bukkit-pro.md) — skill · 131 installs
- [mc-asset — Minecraft Pixel Asset Engine](https://affpapa.org/en/nevibecode/mcp/mc-asset-minecraft-pixel-asset-engine.md) — MCP server · ★ 5 repo stars
- [Minecraft Wiki](https://affpapa.org/en/nevibecode/mcp/minecraft-wiki.md) — MCP server

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
