---
id: mcpylib
version: "1.1.1"
license: Non-Commercial License - See LICENSE file for details
license_treatment: noncommercial
maintenance: active
---

# mcpylib — Python library for controlling Minecraft servers with python code.

License: noncommercial · Maintenance: active · Downloads: 544.9K/mo

## What it is and what it does

MCPyLib is a client library that connects to a Minecraft server over the network and lets you control it programmatically from Python code. It provides methods to place and query individual blocks, fill regions, teleport players, change game modes, and manipulate world time and weather. The library depends on python-dotenv for configuration management and requires Python 3.11 or later.

The package is in active development (alpha status) with a small but growing user base. It is licensed under a Non-Commercial License, which means it is free to use for personal projects and learning but cannot be used in commercial or monetized applications without explicit permission. The library is straightforward to install and has low dependency friction, making it accessible for hobby Minecraft server automation and scripting.

Use it for:

- Automate world-building tasks like filling large regions with blocks or placing structures programmatically.
- Build admin tools that teleport players, change game modes, or manage world time without manual commands.
- Create event systems or game logic that responds to server state by querying player positions and modifying the world.
- Develop testing or validation scripts for Minecraft server configurations and world state.
- Integrate Minecraft server control into a larger application or bot framework for community management.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

MCPyLib is a Python client library for remotely controlling Minecraft servers, allowing you to place and query blocks, manage players, and manipulate world state through a programmatic API.

Yes, if you are building a non-commercial Minecraft server automation tool or hobby project. The package is actively maintained, has low install friction, and provides a clean API for common server control tasks. However, the non-commercial license is a hard blocker for any monetized or commercial use, and the alpha status means the API and behavior may change. Verify that your target server software supports the remote control API MCPyLib expects before committing to it.

## Install

pip install mcpylib
uv add mcpylib
poetry add mcpylib

## Installing mcpylib

Before you install: Low install friction with a pure-Python wheel and only one runtime dependency (python-dotenv). The package is actively maintained with recent commits, though it is still in alpha status (Development Status :: 3 - Alpha).

License in practice: Licensed under a Non-Commercial License. This restricts use to non-commercial purposes only—commercial projects or monetized applications would need explicit permission or an alternative license.

Quickstart:

pip install mcpylib

from mcpylib import MCPyLib

mc = MCPyLib(ip="127.0.0.1", port=65535, token="your_token")
mc.setblock(100, 64, 200, "minecraft:diamond_block")
block = mc.getblock(100, 64, 200)
print(f"Block: {block}")

Requires Python 3.11 or later. A running Minecraft server with the appropriate remote control API enabled and a valid authentication token are also required.

Verify before relying:

- Which Minecraft server software (Bukkit, Spigot, Paper, etc.) or plugin is required to expose the remote control API that MCPyLib connects to.
- Whether the server-side setup and token generation process is documented or straightforward for new users.
- Performance characteristics and latency impact when issuing commands to a remote server.

## Package facts

- License: Non-Commercial License - See LICENSE file for details (noncommercial)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 544.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

minecraft server remote control python, minecraft api client library, programmatic block placement minecraft, minecraft server automation, minecraft python scripting, remote minecraft commands, minecraft world manipulation api, minecraft, game-automation, noncommercial-license

[View on SkillFed](https://skillfed.io/packages/mcpylib) · [View on PyPI](https://pypi.org/project/mcpylib/)