Minecraft Item Finder

Ever spent hours searching through thousands of chests for that one precious item you forgot where you stored?

This Python script scans your Minecraft Java Edition world files to instantly locate any item across all containers, armor stands, and placed blocks.

What it does

• Searches all containers: chests, barrels, shulker boxes, hoppers, dispensers, etc.
• Finds placed items: armor on armor stands, books in lecterns, skulls as decoration
• Scans all dimensions: Overworld, Nether, End
• Smart filtering: excludes common blocks (stone, dirt) to avoid spam
• Groups results: organizes output by chunk and item type for readability
• Interactive interface: prompts for dimension and search terms

Installation

Install Python 3

# macOS (with Homebrew)
brew install python3

# Ubuntu/Debian
sudo apt update && sudo apt install python3 python3-pip

# Windows - download from python.org

Install NBT library

pip3 install nbt

Download script

# Download from GitHub
curl -O https://raw.githubusercontent.com/bluantinoo/Minecraft-Finder/main/minecraft_item_finder.py

# Or clone the repository
git clone https://github.com/bluantinoo/Minecraft-Finder.git
cd Minecraft-Finder

Configuration

Edit the script to set your world name:

self.world_name = "Your World Name Here"  # Line 9

Usage

Run the script:

python3 minecraft_item_finder.py

Follow the prompts:

1. Choose dimension (1=Overworld, 2=Nether, 3=End)
2. Enter search term (item name or partial match)

Search Examples

• trident - finds tridents in containers or item frames
• diamond - finds all diamond items (sword, pickaxe, helmet, etc.)
• shulker_box - finds all shulker boxes
• skull - finds all placed skulls and skull items
• netherite - finds netherite gear
• elytra - finds elytra wings
• beacon - finds placed beacons

Placed Block Detection

The script finds items in these special locations:

Skulls (placed as decoration):

• Skeleton skulls, wither skeleton skulls, zombie heads
• Player heads, creeper heads, dragon heads
• Searches both SkullType numbers and names

Armor Stands:

• Armor pieces (helmet, chestplate, leggings, boots)
• Items in hands (main hand, off hand)

Other Placed Items:

• Books in lecterns
• Placed beacons
• Placed conduits
• Dragon heads as wall decoration

Output Format

📍 Chunk (5, -29)
  🎒 minecraft:trident x1 in minecraft:barrel
  🎒 minecraft:diamond_sword x2 in 3 minecraft:chests

📊 Total: 3 item(s) in 1 chunk(s)

Technical Details

• File format: Scans .mca region files in world/region/ directories
• NBT parsing: Uses Python NBT library to read compressed chunk data
• Memory efficient: Processes one region at a time
• Error handling: Continues scanning if individual chunks fail to load
• Result limiting: Shows max 50 results to prevent terminal overflow

Limitations

• Java Edition only (Bedrock uses different file format)
• World must be closed while scanning
• Large worlds: may take several minutes to scan 500+ regions
• Modded items: may not recognize non-vanilla item IDs

Troubleshooting

"Dimension not found": The dimension folder doesn't exist (never explored that dimension) "No results": Try shorter/broader search terms like "diamond" instead of "diamond_sword" "Permission denied": Make sure Minecraft is closed and files aren't locked "NBT library error": Run pip3 install --upgrade nbt

License

This project is licensed under the MIT License - see the LICENSE file for details.