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.