minecraft-remote-api

マイクラリモコン（Minecraft Remote / mc-remote）のための公式Pythonクライアント／APIパッケージです。Pythonコードを書いて、最新のマインクラフトの世界を自由にプログラミング・自動建築できます。

🏠 公式サイト: mc-remote.com

Note

🌐 言語方針について / Language Policy
本リポジトリは、一次情報（SSOT）の鮮度と正確性を保つため、日本語を正本として記述しています。多言語参加やIssue/PRの利用方針については主要言語についての方針転換 / Language Policy をご覧ください。
This repository is maintained in Japanese as its primary Single Source of Truth (SSOT). Multi-language contributions are welcome. Please see our Language Policy.

3分で動かす（最短クイックスタート）

前提: uv がインストールされていること。Python本体はuvが用意します。 Minecraft側は、B8対応の McRemote を使うサーバーへ接続します。

Step 1: プロジェクトを作り、モジュールを追加

uv init --python 3.13 mc-hello
cd mc-hello
uv add https://github.com/Naohiro2g/minecraft-remote-api/releases/download/v2320.0.0b8/minecraft_remote_api-2320.0.0b8-py3-none-any.whl

現在は、新プロトコル版がPyPIに未登録なので、GitHub.comのリリースに添付されたパッケージを使います。

Step 2: 最小コード（`hello.py`）を書く

mc-hello フォルダに hello.py を作ります。

from mc_remote import Minecraft
# 同じPCで動くB8対応サーバーに接続
mc = Minecraft.create(address="localhost", port=25575)

# 建築原点の設定
mc.setBuildOrigin(200, 0, 200)

# チャット送信
mc.postToChat("Hello, Minecraft from Python!")

# プレイヤー位置、視線方向の設定
mc.setPos("overworld", 30, 120, 30)  # (230, 120, 230) に移動
mc.setDirection(-1, -2, -1)

# ブロック設置
# 建築原点からの相対計算で実際は (205, 67, 205) に置かれます。
mc.setBlock(5, 67, 5, "sea_lantern")

サーバーが別のPCにある場合は、localhost をその接続先に置き換えます。公式箱庭を使う場合は、公式サイトの接続先と対応版の案内を確認してください。

Step 3: 実行とペアリング

uv run hello.py

ターミナルに表示される /mcremote pair NNN-NNN をゲーム内チャットに貼り付け、Enterを押すと認証が完了します。認証は2時間有効です。チャットに Hello, Minecraft from Python! と表示され、(205, 67, 205) にシーランタンが光れば成功です。

Jupyter Notebookで1行ずつ実行する

コードを1行ずつ実行して、マイクラの世界がどう変わるかを確かめながら進められます。Step 1で作った mc-hello フォルダで作業します。

VS Codeで使う

ノートブックの実行に必要なカーネルを、開発用の依存として追加します。
```
uv add --dev ipykernel
```
VS Codeに拡張機能「Jupyter」（Microsoft）を入れ、mc-hello フォルダを開きます。
hello.ipynb などのノートブックを作り、右上の「カーネルの選択」→「Python環境」から mc-hello の .venv を選びます。
セルに hello.py の内容を分けて書き、1つずつ実行します。ペアリング用の /mcremote pair NNN-NNN はセルの出力に表示されます。

JupyterLabで使う

uv add --dev jupyterlab
uv run jupyter lab

ブラウザでJupyterLabが開きます。新しいノートブックを作れば、mc-hello の環境でそのまま実行できます。

`.py` を書き換えたら、カーネルを再起動する

import したモジュールは、カーネルの中にキャッシュされます（中身は sys.modules で確かめられます）。2回目以降の import はこのキャッシュを使うので、自分で作った .py や mc_remote 自体を書き換えても、変更は自動では反映されません。書き換えたら、カーネルを再起動してキャッシュを空にしてください。

カーネルを再起動したあとは、import や mc の設定など、マイクラリモコンサーバーとの接続もやり直しが必要になります。ただし、上から全部実行はおすすめしません。

手早く再起動するには

JupyterLab：Esc を押してから 0 を2回。
VS Code：ノートブック上部の「Restart」。キーボードショートカットに割り当てることもできます。

セルから再起動する（JupyterLab）：

mc.close()   # マイクラとの接続を閉じる
import os
os._exit(0)  # カーネルが止まり、JupyterLab が自動で起動し直す

本格的な学習とスターター（`starter/`）

環境を安全に分離し、VS Code等のエディタで ブロック名やアイテム名の自動補完（IntelliSense） を獲得するための公式スターターキットが用意されています。

git clone https://github.com/Naohiro2g/minecraft-remote-api.git
cd minecraft-remote-api
uv sync --frozen
cd starter
cp param_mc_remote.template.py param_mc_remote.py
uv run python hello.py

環境アダプター (param_mc_remote.py): サーバー接続先や建築原点をプログラム本体から分離します（Git管理外）。
生きたカタログ補完 (mc_constants): 初回接続時に接続先サーバーのブロック定義を自動取得し、Pythonコード内で block.SEA_LANTERN のような正確な型補完が効くようになります。
詳しい段階的学習法は starter/README_ja.md をご覧ください。

主な機能と作例

チャットとプレイヤー操作: mc.postToChat(), mc.getPos(), mc.setPos(), mc.getDirection(), mc.setDirection()
ブロックの設置と取得: mc.setBlock(), mc.getBlock(), mc.setBlocks()
看板の読み書き: mc.setSign(), mc.getSign(), mc.updateSignLine()
演出とイベント: mc.spawnParticle(), mc.strikeLightning(), mc.pollEvents()（ツルハシで叩いた検知など）
高速建築モード: DEBUG（1行ずつ確認）、TRACE（動作を観察）、FAST（超高速建築）

公開済みのB8ではentityの検索・pose操作、particleの色・表示先、サウンドを使えます。 B8 APIと3D graphの利用例を参照してください。 B8では from mc_remote import Minecraft が使え、pygameは必要なときに uv add pygame-ce で追加します。パッケージ側のoptional extraは pygame です。導入試験には Windows 11の入口手順を用意しています。

Pythonの呼び出し方・引数・戻り値は PythonクライアントAPI一覧（ドラフト）で用途別に探せます。サーバーの操作と、WireScopeで見える通信の引数・応答は Protocol API一覧で確認できます。 Pythonの mc.playSound(...) は一覧の world.playSound に対応します。Pythonでの引数の渡し方は各作例を参照してください。

パッケージ情報 & 対応環境

パッケージ名: minecraft-remote-api（インポート名: mc_remote）
現行バージョン: 2320.0.0b8（Protocol 23.2.0 準拠、GitHub prerelease公開済み）
対応Python: 3.10〜3.13（標準は3.13）
対応マインクラフト: Java版 1.21.11（Paper 26.x対応準備中）
接続先:
- 公式箱庭（サンドボックス）サーバー: sb-beta.mc-remote.com:25575
- 自前サーバー: PaperMC サーバーに McRemote プラグインを導入して起動
コミュニティ & サポート: Discord サーバー内の #mc-remote-chat チャンネル

開発者向け情報・ライセンス

開発環境のセットアップ (uv)

git clone https://github.com/Naohiro2g/minecraft-remote-api.git
cd minecraft-remote-api
uv sync

pyenv／pip／Poetryを使っていた方は uvへの移行ガイドをご覧ください。

ライセンス

Python クライアントコード本体: MIT License
同梱 WireScope browser app (@mc-remote/live): AGPL-3.0-only
- ソースコード、ライセンス条項、アセットハッシュ値の検証データは GitHub Releases および LICENSE を参照してください。

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
LICENSES		LICENSES
docs		docs
examples		examples
images		images
mc_remote		mc_remote
scripts		scripts
starter		starter
tests		tests
.gitignore		.gitignore
.python-version		.python-version
AGENTS.md		AGENTS.md
LICENSE		LICENSE
Makefile		Makefile
PUBLISHING.md		PUBLISHING.md
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository files navigation

minecraft-remote-api

3分で動かす（最短クイックスタート）

Step 1: プロジェクトを作り、モジュールを追加

Step 2: 最小コード（`hello.py`）を書く

Step 3: 実行とペアリング

Jupyter Notebookで1行ずつ実行する

VS Codeで使う

JupyterLabで使う

`.py` を書き換えたら、カーネルを再起動する

本格的な学習とスターター（`starter/`）

主な機能と作例

パッケージ情報 & 対応環境

関連プロジェクト & 設計思想

開発者向け情報・ライセンス

開発環境のセットアップ (uv)

ライセンス

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

minecraft-remote-api

3分で動かす（最短クイックスタート）

Step 1: プロジェクトを作り、モジュールを追加

Step 2: 最小コード（hello.py）を書く

Step 3: 実行とペアリング

Jupyter Notebookで1行ずつ実行する

VS Codeで使う

JupyterLabで使う

.py を書き換えたら、カーネルを再起動する

本格的な学習とスターター（starter/）

主な機能と作例

パッケージ情報 & 対応環境

関連プロジェクト & 設計思想

開発者向け情報・ライセンス

開発環境のセットアップ (uv)

ライセンス

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Step 2: 最小コード（`hello.py`）を書く

`.py` を書き換えたら、カーネルを再起動する

本格的な学習とスターター（`starter/`）