Flashback MCP

Your Minecraft replays. Your AI assistant. One creative workflow.

Control replay playback, compose camera shots, edit keyframes and export videos from your favorite local MCP-compatible AI client.

English · Italiano

Download the server · Get the mod · Installation · Report an issue

Flashback MCP connects an AI assistant to Flashback, the Minecraft replay editor. Describe the shot you want, inspect the timeline together, preview frames and turn a replay into a finished video using 22 tools exposed through the Model Context Protocol.

This repository contains the Node.js MCP server. Install the companion Flashback MCP Fabric mod in Minecraft to connect it to the game. The server has no npm dependencies and needs no provider API key of its own; your AI client manages its model and account.

What you can do

Examples to ask your assistant after connecting:

“Show my available replays and open the newest one.”

“Create a smooth camera move between these two positions and preview the first and last frames.”

“Hide the HUD, set the export range to the camera path and export the scene as a video.”

The assistant uses the tools; Minecraft and Flashback perform the editing and rendering. Tool and image availability depends on the client and model you use.

Related MCP server: popcorn

Requirements

Run Minecraft and the MCP process on the same computer, under the same operating-system user. WSL, containers and remote executors do not automatically share the Windows game's home directory and connection.

Installation

1. Install the Minecraft mod

1. Open the mods folder of the Minecraft profile you actually use.

2. Install Fabric, Flashback and the dependencies listed on their download pages for Minecraft 26.1.2.

3. Download Flashback MCP 1.0.0 from Modrinth and put flashback-mcp-1.0.0.jar in that profile's mods folder. Replace any older Flashback MCP JAR to avoid loading duplicates.

The .jar belongs in Minecraft's mods folder. The .mjs server below belongs in a separate permanent folder on your computer.

2. Download the MCP server

Install Node.js and check it from a terminal:

node --version

Download flashback-mcp-server.mjs and save it somewhere permanent, for example C:\Tools\FlashbackMCP\ on Windows or ~/Tools/FlashbackMCP/ on macOS/Linux. The release page also offers a ZIP with both guides and SHA-256 checksums.

The standalone file includes the tool catalog: no npm install, Python or build step is needed to use it. Keep the .mjs extension when saving the file.

3. Generate your client configuration

On Windows PowerShell, replace the example path with the location where you saved the file:

node "C:\Tools\FlashbackMCP\flashback-mcp-server.mjs" --print-config codex

On macOS/Linux:

node "$HOME/Tools/FlashbackMCP/flashback-mcp-server.mjs" --print-config codex

Replace codex with the value for your client in the table below. The command prints configuration with the actual absolute paths to Node.js and the server; it does not change any settings. Merge the flashback entry into the indicated file, preserving your existing settings and other MCP servers.

~ means your operating-system home directory, such as C:\Users\YourName on Windows. In JSON, merge into an existing mcpServers or servers object instead of adding a second object with the same name. In TOML, use a single [mcp_servers.flashback] section.

Do not put --print-config in the saved launch arguments. The AI client should run only Node.js plus the full path to the .mjs file. It starts and stops the server for you.

CLI shortcuts

If you prefer command-line registration, use your real absolute path:

codex mcp add flashback -- node "/absolute/path/to/flashback-mcp-server.mjs"
codex mcp get flashback

claude mcp add --transport stdio --scope user flashback -- node "/absolute/path/to/flashback-mcp-server.mjs"

For Codex, the generated TOML also sets tool_timeout_sec = 1200; add this to the registered entry for long replay loads or exports. Gemini's generated configuration sets the same 20-minute timeout in milliseconds. If PowerShell blocks an npm CLI's .ps1 launcher, use its .cmd launcher, such as codex.cmd.

4. Enable the bridge and verify the connection

1. Launch the Minecraft profile containing Flashback and Flashback MCP.

2. From the title screen or pause menu, choose MCP → Enable MCP server.

3. Restart or reconnect your AI client and enable/trust the MCP server when the client asks.

4. Ask: “Call flashback_status and tell me whether Minecraft is connected.”

A successful call reports the game state, for example menu, in_world, replay or exporting. Open a replay before using timeline and camera-editing tools. For screenshots and video export, switch Minecraft to windowed mode with F11.

How it connects

flowchart LR
    A[Local AI client] -->|MCP over stdio| B[Node.js server]
    B -->|Authenticated localhost HTTP| C[Flashback MCP mod]
    C --> D[Minecraft + Flashback]

The mod writes connection details to ~/.flashback-mcp/bridge.json. The server discovers them automatically and connects to 127.0.0.1; you do not need to configure a port or paste a token. Keep that discovery file private. FLASHBACK_MCP_BRIDGE_FILE can select a different local discovery file for advanced setups.

This release provides a local stdio server, not a public HTTP MCP endpoint. Browser-only/cloud clients and clients that accept only HTTP MCP require a separate compatible local integration. Requests and screenshots are passed to your chosen AI client, whose model and data policies apply.

Troubleshooting

When reporting an issue, include game/mod/Node versions, the client name and the error message. Do not include the contents of bridge.json or private client credentials.

Source and validation

flashback-mcp-server.mjs  Ready-to-use standalone server
mcp-server/server.mjs    Source server
mcp-server/tools.json    Full catalog and schemas for all 22 tools
scripts/                 Standalone build script
tests/                   MCP protocol and interoperability tests
README.md                English guide
README.it.md             Guida in italiano

To work on the server:

git clone https://github.com/Jepez00/FlashbackMCP.git
cd FlashbackMCP
npm run build
npm test

No dependency installation is required. Tests additionally require Python 3.11+ to validate generated TOML. The source entry point is mcp-server/server.mjs, with tools.json next to it; it accepts the same --print-config options as the standalone file.

Tests exercise protocol negotiation, tool discovery, error handling, local bridge calls, PNG image responses, simultaneous clients and all six generated configuration formats. They use a mock game bridge; they do not certify every client UI or in-game rendering. MCP revisions supported by this release: 2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25. Newer clients need to negotiate a supported revision.

Credits and documentation

Created by Jepez. Server code and documentation are available under the MIT License. Flashback is created by Moulberry; Minecraft belongs to Mojang / Microsoft. This is an independent project. See third-party notices.

Client configuration references: Codex, Claude Code, Cursor, Gemini CLI, VS Code.