Minestom MCP Server

A stdio MCP server for Minestom, implemented with the Model Context Protocol SDK and TanStack AI tool definitions.

Install

Preferred package invocation:

npx -y minestom-mcp-server

Installed command aliases:

minestom-mcp-server
minestom-mcp

Why this shape:

• minestom-mcp-server is the npm package name and the safest npx entrypoint.

• minestom-mcp is the shorter command alias after install.

• npm npx resolves the matching bin when one of the bin entries matches the package name, so publishing the package as minestom-mcp-server with a minestom-mcp-server bin keeps npx -y minestom-mcp-server reliable. Source: npm npx docs

The tool surface is grounded in:

• the official Minestom docs at minestom.net/docs

• the Minestom javadocs at javadoc.minestom.net

• the Minestom ecosystem directory at minestom.net/libraries

Detailed tool documentation lives in docs/tools.md.

The repository also ships a publish-ready static docs site in docs/ plus a GitHub Pages workflow in /.github/workflows/deploy-docs.yml.

Tools

• ping: verifies that the MCP server is reachable.

• get_server_info: returns package metadata, runtime details, tool inventory, and knowledge-catalog coverage.

• inspect_minestom_environment: inspects the current workspace or repoRoot, including subdirectories, Gradle/Maven build signals, JVM source layouts, detected patterns, entrypoints, existing libraries, and any detected run/ folders.

• inspect_minestom_build: interprets Gradle or Maven modules, including dependencies, plugins, wrapper commands, variables/properties, and Gradle version catalogs.

• explain_minestom_pattern: explains Minestom patterns for bootstrap, instances, events, commands, schedulers, and thread ownership.

• lookup_minestom_api: returns curated API matches with package names, related APIs, and javadoc links.

• plan_minestom_feature: produces a grounded implementation outline for Minestom feature types.

• review_minestom_design: reviews design notes against Minestom’s manager, event, instance, scheduler, and threading patterns.

• suggest_minestom_libraries: returns curated library suggestions, can optionally add live GitHub topic results, and now uses repository signals when available.

Notes

• API lookup is curated around the most important Minestom symbols and patterns; it is not a full javadoc crawler.

• Library discovery is hybrid: curated results are always returned first, live GitHub topic:minestom-library search is optional, and repo-aware ranking can inspect the target project.

• Environment-aware tools default to the current working directory and inspect subdirectories as part of that workspace. You can pass repoRoot to inspect a different Minestom workspace, and run/ is treated as a strong development signal rather than an assumed server root.

• Because Minestom is JVM-based, the environment scan explicitly looks for Gradle/Maven build files, common wrapper scripts, JVM source roots, and Java/Kotlin signals before treating a workspace as a likely Minestom server project.

• Build-aware inspection understands common Gradle dependency/plugin declarations in build.gradle or build.gradle.kts, reads gradle/libs.versions.toml, and parses Maven pom.xml dependencies, plugins, and properties.

Development

pnpm install
pnpm build
pnpm start

For iterative work:

pnpm dev

Publish

The package is set up for npm publishing with:

• executable bins for minestom-mcp-server and minestom-mcp

• a shebang-included bundled entrypoint in dist/server.js

• files whitelisting for the publish tarball

• prepack and prepublishOnly verification hooks

• publishConfig.access = public

Recommended release flow:

pnpm lint
pnpm typecheck
pnpm build
npm pack --dry-run
npm publish