What can you do with this server?

MCModding-MCP is an AI-powered Model Context Protocol server providing real-time access to comprehensive Minecraft modding documentation, code examples, and API mappings for Fabric and NeoForge. Core Capabilities: • Search Documentation (search_fabric_docs) - Query 1,000+ pages of official Fabric/NeoForge documentation with filtering by category (items, blocks, entities, rendering, networking, data-generation, commands, sounds, etc.), loader, and Minecraft version • Get Code Examples (get_example) - Retrieve working code snippets with full context and explanations, filterable by topic, mod loader, category, language, and Minecraft version • Explain Concepts (explain_fabric_concept) - Get detailed explanations of fundamental modding concepts like mixins, registries, sided logic, events, and architectural patterns • Version Information (get_minecraft_version) - Retrieve the latest or all indexed Minecraft versions Key Features: • Hybrid Search - Combines semantic embeddings, full-text, section, and code search strategies for optimal results • Always Current - Weekly-indexed documentation (185K+ chunks) with automatic database updates, hash verification, and backups • Version-Aware - Supports filtering by specific Minecraft versions and mod loaders for accurate information Optional Extended Capabilities (installed via npx mcmodding-mcp manage): • Parchment Mappings Database - Search 831K+ methods and 166K+ fields with parameter names and Javadocs using tools like search_mappings, get_class_details, lookup_obfuscated, get_method_signature, and get_package_classes • Mod Examples Database - Search 1,000+ battle-tested code patterns from popular mods like Create, Botania, and Applied Energistics 2 using search_mod_examples, get_mod_example, list_indexed_mods, and get_mod_categories

How do I use mcmodding-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcmodding-mcp how do I register a custom sword in Fabric for Minecraft 1.21?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCModding-MCP

🤖 AI-Powered Minecraft Modding Documentation Server

Give your AI assistant real-time access to Fabric & NeoForge documentation

GitHub stars GitHub issues GitHub last commit Node.js

📖 Documentation • 🚀 Quick Start • 💡 Features • 🤝 Contributing

✨ What is this?

MCModding-MCP is a Model Context Protocol (MCP) server that supercharges AI assistants like Claude with real, up-to-date Minecraft modding knowledge. No more hallucinations or outdated API references!

🎯 Key Benefits

Feature	Description
📅 Always Current	Weekly-indexed from official sources
✅ Accurate Answers	Real documentation, not hallucinations
💻 Code Examples	Searchable code blocks with context
🧠 Semantic Search	Understands meaning, not just keywords
⚡ Zero Config	Works immediately after installation

📊 Live Statistics

Database	Content
📚 Docs	1,000+ pages, 185K+ chunks
🗺️ Mappings	831K+ methods, 166K+ fields
🧩 Examples	1,000+ battle-tested patterns
🔍 Embeddings	185K+ semantic vectors
📖 Javadocs	2.3M+ documented parameters

Quick Start

Installation

# Install globally npm install -g mcmodding-mcp

Configure Your AI Client

Add to your MCP client configuration (e.g., Claude Desktop):

{ "mcpServers": { "mcmodding": { "command": "mcmodding-mcp" } } }

🧠 Optimized System Prompt

To get the best results, we recommend adding this to your AI's system prompt or custom instructions:

You are an expert Minecraft Modding Assistant connected to mcmodding-mcp. DO NOT rely on your internal knowledge for modding APIs (Fabric/NeoForge) as they change frequently. ALWAYS use the available tools:
search_fabric_docs and get_example for documentation and code patterns
search_mappings and get_class_details for Minecraft internals and method signatures
search_mod_examples for battle-tested implementations from popular mods
Prioritize working code examples over theoretical explanations. When dealing with Minecraft internals, use the mappings tools to get accurate parameter names and Javadocs. If the user specifies a Minecraft version, ensure all retrieved information matches that version.

That's it! Your AI assistant now has access to comprehensive Minecraft modding resources.

Database Management

Manage your documentation databases with the built-in CLI:

# Run the database manager npx mcmodding-mcp manage

The interactive manager allows you to:

Install - Download databases you don't have yet
Update - Check for and apply database updates
Re-download - Restore deleted or corrupted databases

Available Databases

Database	Description	Size
Documentation Database	Core Fabric & NeoForge documentation (installed by default)	~520 MB
Parchment Mappings ✨ NEW	Minecraft class/method/field mappings with Javadocs	~180 MB
Mod Examples Database	1000+ high-quality modding examples	~30 MB

The manager shows version information and highlights available updates:

◉ 📚 Documentation Database [core] ✔ Installed: v0.2.1 → ↻ Update: v0.2.2 [520.3 MB] Core Fabric & NeoForge documentation - installed by default ○ 🗺️ Parchment Mappings Database ✨ NEW ⚠ Not installed → Available: v0.1.0 [178.5 MB] Minecraft class/method/field names with parameter names and Javadocs ○ 🧩 Mod Examples Database ⚠ Not installed → Available: v0.1.0 [28.1 MB] 1000+ high-quality modding examples for Fabric & NeoForge

Available Tools

The MCP server provides powerful tools across three categories:

📖 Documentation Tools

`search_fabric_docs`

Search documentation with smart filtering.

// Example: Find information about item registration { query: "how to register custom items", category: "items", // Optional filter loader: "fabric", // fabric | neoforge minecraft_version: "1.21.10" // Optional version filter }

`get_example`

Get working code examples for any topic.

// Example: Get block registration code { topic: "custom block with block entity", language: "java", loader: "fabric" }

`explain_fabric_concept`

Get detailed explanations of modding concepts with related resources.

// Example: Understand mixins { concept: 'mixins'; }

`get_minecraft_version`

Get current Minecraft version information.

// Get latest version { type: 'latest'; } // Get all indexed versions { type: 'all'; }

🗺️ Parchment Mappings Tools ✨ NEW

Requires Parchment Mappings database - install via

`search_mappings`

Search Minecraft class, method, and field mappings with parameter names and Javadocs.

// Example: Find block-related classes and methods { query: "BlockEntity", type: "class", // class | method | field | all minecraft_version: "1.21.10", include_javadoc: true }

`get_class_details`

Get comprehensive information about a Minecraft class including all methods and fields.

// Example: Explore the Block class { class_name: "net.minecraft.world.level.block.Block", include_methods: true, include_fields: true }

`lookup_obfuscated`

Look up deobfuscated names from obfuscated identifiers (useful for crash logs).

// Example: Decode an obfuscated method name { obfuscated_name: 'm_46859_'; }

`get_method_signature`

Get the full signature of a method including all parameter names and types.

// Example: Get method details { class_name: "Block", method_name: "onPlace" }

`browse_package`

Discover classes in a Minecraft package.

// Example: Browse block package { package_name: 'net.minecraft.world.level.block'; }

🧩 Mod Examples Tools

Requires Mod Examples database - install via

`search_mod_examples`

Search battle-tested code from popular mods like Create, Botania, and Applied Energistics 2.

// Example: Find block entity implementations { query: "block entity tick", mod: "Create", // Optional: filter by mod category: "tile-entities", complexity: "intermediate" }

`get_mod_example`

Get detailed information about a specific example with full code and explanations.

// Example: Get full details for an example { id: 42, include_related: true }

`list_canonical_mods`

Discover all indexed mods and their available examples.

`list_mod_categories`

Browse available example categories (blocks, entities, rendering, etc.).

Features

Hybrid Search Engine

Combines multiple search strategies for best results:

Strategy	Purpose
FTS5 Full-Text	Fast keyword matching with ranking
Semantic Embeddings	Understanding meaning and context
Section Search	Finding relevant documentation sections
Code Search	Locating specific code patterns

Auto-Updates

The database automatically checks for updates on startup:

Compares local version with GitHub releases
Downloads new versions with hash verification
Creates backups before updating
Non-blocking - server starts immediately

Documentation Sources

Currently indexes:

wiki.fabricmc.net - Fabric Wiki (226+ pages)
docs.fabricmc.net - Official Fabric Docs (266+ pages)
docs.neoforged.net - NeoForge Docs (512+ pages)

For Developers

Development Setup

# Clone repository git clone https://github.com/OGMatrix/mcmodding-mcp.git cd mcmodding-mcp # Install dependencies npm install # Run in development mode npm run dev

Build Commands

# Development npm run dev # Watch mode with hot reload npm run typecheck # TypeScript type checking npm run lint # ESLint npm run test # Run tests npm run format # Prettier formatting # Production npm run build # Build TypeScript npm run build:prod # Build with fresh documentation index npm run index-docs # Index documentation with embeddings # Database Management npx mcmodding-mcp manage # Interactive database installer/updater

Project Structure

mcmodding-mcp/ ├── src/ │ ├── index.ts # MCP server entry point │ ├── db-versioning.ts # Auto-update system │ ├── indexer/ │ │ ├── crawler.ts # Documentation crawler │ │ ├── chunker.ts # Text chunking │ │ ├── embeddings.ts # Semantic embeddings │ │ ├── store.ts # SQLite database │ │ └── sitemap.ts # Sitemap parsing │ ├── services/ │ │ ├── search-service.ts # Search logic │ │ └── concept-service.ts # Concept explanations │ └── tools/ │ ├── searchDocs.ts # search_fabric_docs handler │ ├── getExample.ts # get_example handler │ └── explainConcept.ts # explain_fabric_concept handler ├── scripts/ │ └── index-docs.ts # Documentation indexing script ├── data/ │ ├── mcmodding-docs.db # SQLite database │ └── db-manifest.json # Version manifest └── dist/ # Compiled JavaScript

Database Schema

-- Documents: Full documentation pages CREATE TABLE documents ( id INTEGER PRIMARY KEY, url TEXT UNIQUE NOT NULL, title TEXT NOT NULL, content TEXT NOT NULL, category TEXT NOT NULL, loader TEXT NOT NULL, -- fabric | neoforge | shared minecraft_version TEXT, hash TEXT NOT NULL -- For change detection ); -- Chunks: Searchable content units CREATE TABLE chunks ( id TEXT PRIMARY KEY, document_id INTEGER NOT NULL, chunk_type TEXT NOT NULL, -- title | section | code | full content TEXT NOT NULL, section_heading TEXT, code_language TEXT, word_count INTEGER, has_code BOOLEAN ); -- Embeddings: Semantic search vectors CREATE TABLE embeddings ( chunk_id TEXT PRIMARY KEY, embedding BLOB NOT NULL, -- 384-dim Float32Array dimension INTEGER NOT NULL, model TEXT NOT NULL -- Xenova/all-MiniLM-L6-v2 ); -- FTS5 indexes for fast text search CREATE VIRTUAL TABLE documents_fts USING fts5(...); CREATE VIRTUAL TABLE chunks_fts USING fts5(...);

Release Workflow

This project uses release-please for automated releases.

Branch Strategy

Branch	Purpose
`dev`	Active development
`prod`	Production releases

How It Works

Push commits to dev using conventional commits
Release-please maintains a Release PR (dev → prod)
When merged, automatic release: npm publish + GitHub release + database upload
Changes sync back to dev

See RELEASE_WORKFLOW.md for complete details.

Configuration

Environment Variables

Variable	Description	Default
`DB_PATH`	Custom database path	`./data/mcmodding-docs.db`
`GITHUB_REPO_URL`	Custom repo for updates	Auto-detected
`MCP_DEBUG`	Enable debug logging	`false`

Disabling Auto-Updates

Set DB_PATH to a custom location to manage updates manually:

DB_PATH=/path/to/my/database.db mcmodding-mcp

We're actively developing mcmodding-mcp and want to hear from you!

Have an Idea?

Feature requests - What tools would make your modding easier?
New documentation sources - Know a great modding resource we should index?
Workflow improvements - How could the tools work better for your use case?

👉 Open a Feature Request

Found a Bug?

Incorrect search results?
Missing or outdated documentation?
Tool not working as expected?

👉 Report a Bug

Using mcmodding-mcp for a cool project? We'd love to hear about it! Share your story in Discussions.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Contribution Guide

Fork the repository
Create a feature branch from dev
Make changes with conventional commits
Submit a PR to dev

License

MIT License - see LICENSE for details.

Changelog

See CHANGELOG.md for a detailed history of changes and releases.

Acknowledgments

Fabric Documentation - Official Fabric documentation
Fabric Wiki - Community wiki
NeoForge Documentation - Official NeoForge documentation
ParchmentMC - Parameter names and Javadoc mappings
Model Context Protocol - MCP specification
Transformers.js - Local ML embeddings
better-sqlite3 - Fast SQLite bindings

🎮 Built with ❤️ for the Minecraft modding community

If you find this project useful, please consider giving it a ⭐!

⬆️ Back to Top

Install Server

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

Resources

Need Help?

Report Issue

Related Servers