Viper LLM

ViperLLM

ViperLLM is a Fabric mod that connects vanilla Minecraft chat to Large Language Model providers. Players talk to AI assistants through normal chat, and the assistants can read live game data (inventory, recipes, position, weather, containers, signs, books and more) through a built-in @tool system. It works on dedicated servers and in singleplayer (integrated server). No client mod is required: vanilla clients can join a ViperLLM server and use it immediately.

Supported providers: OpenAI, OpenRouter, LM Studio, Ollama, Anthropic and any OpenAI-compatible endpoint, with automatic endpoint detection and fallback.

Supported versions

| Minecraft | Java | Loader |
|—|—|—|
| 1.21.1 | 21 | Fabric Loader 0.19.x |
| 26.1 | 25 | Fabric Loader 0.19.x |
| 26.2 | 25 | Fabric Loader 0.19.x |
| 26.3 | 25 | Fabric Loader 0.19.5 |

Download the file whose version number matches your exact Minecraft version (for example 1.0.0+1.21.1 for Minecraft 1.21.1). Mixins are version-exact, so mismatched builds will not load.

Installation

Singleplayer: put the jar in your client’s mods folder and launch the Fabric profile. Open your world and run the setup commands below (cheats must be enabled).

Dedicated server: put the jar in the server’s mods folder and restart. Connect with any vanilla client. No API key is bundled: each player configures their own key with the commands below.

Setup

/llm configure cloud
/llm set cloud apikey YOUR_API_KEY
/llm test
/llm ask Hello!

For a local model server (LM Studio / Ollama, operator only by default):

/llm scan http://192.168.1.50:1234
/llm configure local http://192.168.1.50:1234 qwen3.5-4b YOUR_API_KEY
/llm select local
/llm set local model list

Commands

| Command | Description |
|—|—|
| /llm configure <id> | Create and activate an instance from global defaults |
| /llm configure <id> <url> <model> [api_key] | Detect and configure a custom endpoint, optionally with API key |
| /llm scan <url> [api_key] | Detect endpoint format and available models (key used only for the scan) |
| /llm select <id> | Select an existing instance |
| /llm delete <id> | Delete an instance |
| /llm info | Show profile and active-instance details |
| /llm test | Send an OK test through the active instance |
| /llm ask <message> | Send a message to the active LLM |
| /llm upload <url> <message> | Send a media URL with a prompt |
| /llm clearmemory | Clear conversation memory (short-term history and long-term summary) |
| /llm mode PRIVATE\|GLOBAL | Change response routing mode |
| /llm global | Toggle routing all of your chat to the LLM (messages stay visible in chat) |
| /llm commands | Toggle command-tool permission for your profile |
| /llm set <id> apikey <key> | Set a per-instance API key |
| /llm set <id> url <url> | Change an instance endpoint |
| /llm set <id> model <name> | Change an instance model |
| /llm set <id> model list | Show available endpoint models as an in-game book |
| /llm set <id> prompt <text> | Append custom instructions after the built-in rules |
| /llm set <id> temperature <0-2> | Change sampling temperature |
| /llm set <id> timeout <5-120> | Set the HTTP timeout in seconds |
| /llm set <id> prefix <text> | Change the response prefix |
| /llm set <id> color <code> | Change the response color |
| /llm set <id> context playerdata <true\|false> | Toggle player-data context |
| /llm set <id> context inventory <true\|false> | Toggle inventory context |
| /llm set <id> context recipes <true\|false> | Toggle recipe context |
| /llm set <id> context maxrecipes <number> | Set the recipe context limit |

LLM tools

The assistant calls these itself when it needs live data. Tool calls never appear in chat, only the final answer. Malformed tool markup (for example DSML-style output from small local models) is repaired into real tool calls automatically, and the model is asked to retry when a call cannot be parsed.

| Tool | Returns |
|—|—|
| @player_stats | Dimension, health, food, XP, game mode, position |
| @inventory | Held items, armor, hotbar and full main inventory (all 27 slots) |
| @search_recipes | Crafting recipes for an item (fuzzy fallback, modded namespace:item supported) |
| @search_items / @search_blocks | Matching registered item / block IDs |
| @biome / @time / @weather / @difficulty | Current biome, time and phase, weather, difficulty |
| @effects | Active potion effects with durations |
| @look / @standing / @spawn | Targeted block, block below, world spawn |
| @nearby | Nearby entities plus what the player is looking at |
| @online | Players currently on the server |
| @enchant | Enchantments on the held item |
| @stats | Deaths, damage, kills, play time, distance |
| @advancements | Completed advancements |
| @read_book | Title, author and pages of a held or stored book |
| @chest_inv | Contents of the looked-at chest, barrel, shulker, hopper, ender chest or minecart |
| @read_sign | Front and back text of the looked-at sign |
| @find_block | Nearest matching block within the configured radius |
| @look_around | Full environment summary |
| @command | Runs a Minecraft command with the player’s own permission level |
| @tools | Lists available tools |

Global configuration

File: config/viperllm.json (restart the server after editing).

| Field | Description |
|—|—|
| defaultProvider | Provider type used for default instances |
| defaultModel | Default model identifier |
| defaultUrl | Default full chat endpoint |
| defaultApiKey | Optional global fallback key, empty by default |
| defaultMaxTokens | Default output-token ceiling |
| defaultTemperature | Default sampling temperature |
| defaultTopP | Default nucleus-sampling value |
| debug | Extra diagnostic logging |
| contextPlayerData | Global player-data context default |
| contextInventory | Global inventory context default |
| contextRecipes | Global recipe context default |
| contextMaxRecipes | Global recipe context limit |
| allowCommandExecution | Server-wide master switch for @command (default true) |
| allowPrivateNetworkScanning | Let all players scan LAN endpoints (default false) |
| allowPrivateNetworkScanningForOperators | Let operators scan LAN endpoints (default true) |
| findBlockRadius | Search radius for @find_block (default 16) |

The default system prompt is built into the mod. /llm set <id> prompt <text> appends your own instructions on top of it.

Safety

• @command needs both the global and the per-player switch, and it always runs with the owning player’s own permission level. It never elevates permissions.
• Localhost and LAN endpoint scanning is restricted to operators unless the server config opens it, so normal players cannot use the scanner as a network probe.
• API keys are stored as plaintext in server-side profiles (world/viperllm/players/<UUID>.json). Protect the world directory and backups.

License

MIT. Requires Fabric Loader only. No Fabric API needed.