# Minecraft Mcp

> MCP server for minecraft

- **Type:** MCP server
- **Install:** `agentstack add mcp-fundamentallabs-minecraft-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [FundamentalLabs](https://agentstack.voostack.com/s/fundamentallabs)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [FundamentalLabs](https://github.com/FundamentalLabs)
- **Source:** https://github.com/FundamentalLabs/minecraft-mcp

## Install

```sh
agentstack add mcp-fundamentallabs-minecraft-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Fundamental Labs/Minecraft Client

This library is the Client library for a Minecraft Game Skills and MCP Integration.

Fairies MCP Client () also supports direct connection with a single click.

## Features

- **Full Minecraft Control**: Connect AI agents to Minecraft servers and control bots
- **30 Verified Skills**: Pre-built, tested skills for common Minecraft tasks
- **Flexible Connection**: Connect to any Minecraft server with optional per-bot configuration
- **Multi-Bot Support**: Manage multiple bots simultaneously
- **MCP Standard**: Compatible with any MCP client (Claude Desktop, etc.)

## Installation

### Direct call via npx (Recommended)

```bash
npx --y -- @fundamentallabs/minecraft-mcp
```

### Via npm (Recommended)

```bash
npm install -g @fundamentallabs/minecraft-mcp
```

### From Source

```bash
git clone https://github.com/FundamentalLabs/minecraft-mcp.git
cd minecraft-mcp/minecraft-client/mcp-server
npm install
npm run build
```

## Usage

### Starting the Server

You can start the MCP server with optional default connection settings:

```bash
# Start with no defaults (connection specified per bot)
minecraft-mcp

# Start with default connection settings
minecraft-mcp -h play.example.com -p 25565
```

### Command Line Options

```bash
Options:
  -p, --port   Minecraft server port (default: 25565)
  -h, --host   Minecraft server host (default: localhost)
  --help            Display help
```

### Integration with Claude Desktop or JSON configurations Locally

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

For remote installation (recommended)

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": ["-y", "-- @fundamentallabs/minecraft-mcp"]
    }
  }
}
```

If running locally from source:

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/path/to/minecraft-mcp/minecraft-client/mcp-server/dist/mcp-server.js"]
    }
  }
}
```

Replace `/path/to/minecraft-mcp` with the actual path where you cloned the repository.

### Integration with Other MCP Clients

The server uses stdio transport and can be integrated with any MCP client:

```bash
# Using the MCP inspector for testing
cd minecraft-client/mcp-server
npx @modelcontextprotocol/inspector node dist/mcp-server.js -- -p 25565
```

## Available Skills

### Bot Management

- **joinGame** - Spawn a new bot into the Minecraft game
  - `username` (required): Bot's username
  - `host` (optional): Server host (defaults to 'localhost' or command line option)
  - `port` (optional): Server port (defaults to 25565 or command line option)

- **leaveGame** - Disconnect bot(s) from the game
  - `username` (optional): Specific bot to disconnect
  - `disconnectAll` (optional): Disconnect all bots if true

### Movement & Navigation

- **goToSomeone** - Navigate to another player
- **goToKnownLocation** - Navigate to specific coordinates
- **runAway** - Run away from threats
- **swimToLand** - Swim to nearest land when in water

### Combat & Hunting

- **attackSomeone** - Attack players, mobs, or animals
- **hunt** - Hunt animals or mobs

### Resource Gathering

- **mineResource** - Mine specific blocks or resources
- **harvestMatureCrops** - Harvest mature crops from farmland
- **pickupItem** - Pick up items from the ground

### Crafting & Smelting

- **craftItems** - Craft items using a crafting table
- **cookItem** - Cook items in a furnace
- **smeltItem** - Smelt items in a furnace
- **retrieveItemsFromNearbyFurnace** - Get smelted items from furnace

### Inventory Management

- **openInventory** - Open the bot's inventory
- **equipItem** - Equip armor, tools, or weapons
- **dropItem** - Drop items from inventory
- **giveItemToSomeone** - Give items to another player

### Building & Farming

- **placeItemNearYou** - Place blocks near the bot
- **prepareLandForFarming** - Prepare land for farming
- **useItemOnBlockOrEntity** - Use items on blocks or entities

### Survival

- **eatFood** - Eat food to restore hunger
- **rest** - Rest to regain health
- **sleepInNearbyBed** - Find and sleep in a bed

### Storage

- **openNearbyChest** - Open a nearby chest

### Fun

- **dance** - Make the bot dance

### Vision

- **lookAround** - Look around and observe the environment

### Communication

- **readChat** - Read recent chat messages from the server
- **sendChat** - Send chat messages or commands to the server

### Building

- **buildSomething** - Build structures using Minecraft commands (requires cheats/operator permissions). Supports both static command arrays and dynamic JavaScript code.
- **buildPixelArt** - Build pixel art from an image in Minecraft (requires cheats/operator permissions). Converts an image to pixel art using colored blocks. Maximum size is 256x256 blocks.

## API Example

When integrated with an MCP client, you can control the bot like this:

```javascript
// First, spawn a bot
await client.callTool('joinGame', { username: 'MyBot' });

// Make the bot mine some wood
await client.callTool('mineResource', { name: 'oak_log', count: 10 });

// Craft wooden planks
await client.callTool('craftItems', { item: 'oak_planks', count: 40 });

// Navigate to coordinates
await client.callTool('goToKnownLocation', { x: 100, y: 64, z: 200 });

// Build a structure using commands (requires cheats) - Script mode
await client.callTool('buildSomething', {
  buildScript: [
    { command: "fill", x1: 0, y1: 64, z1: 0, x2: 10, y2: 64, z2: 10, block: "stone" },
    { command: "fill", x1: 1, y1: 65, z1: 1, x2: 9, y2: 68, z2: 9, block: "oak_planks" },
    { command: "setblock", x: 5, y: 65, z: 1, block: "oak_door" }
  ]
});

// Build dynamically with JavaScript (requires cheats) - Code mode
await client.callTool('buildSomething', {
  code: `
    // Build a pyramid centered on the bot
    const size = 10;
    for (let y = 0; y = 18.0.0
- A Minecraft server (Java Edition) to connect to
- An MCP-compatible client (like Claude Desktop)

## Troubleshooting

### "Skill implementation not found" Error

The MCP server needs to be run from the cloned repository with built skills. Make sure you:

1. Cloned the full repository
2. Ran `npm install` in the minecraft-client directory
3. Ran `npm run build` in the minecraft-client directory
4. Are running the MCP server from the correct directory

### Bot won't connect

- Ensure your Minecraft server is running and accessible
- Check that the port and host are correct
- Verify the server allows the Minecraft version the bot uses

### Skills not working

- Make sure the bot has spawned successfully before using skills
- Some skills require specific items or conditions
- Check the bot's console output for error messages

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT - see LICENSE file for details

## Support

For issues and feature requests, please use the [GitHub issue tracker](https://github.com/FundamentalLabs/minecraft-mcp/issues).

### Testing

To test with the Anthropic MPC inspector

'npx @modelcontextprotocol/inspector node ./dist/mcp-server.js'

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [FundamentalLabs](https://github.com/FundamentalLabs)
- **Source:** [FundamentalLabs/minecraft-mcp](https://github.com/FundamentalLabs/minecraft-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-fundamentallabs-minecraft-mcp
- Seller: https://agentstack.voostack.com/s/fundamentallabs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.