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

Installed command aliases:

minestom-mcp
minestom-mcp-server

Why this shape:

• minestom-mcp is the npm package name and the default npx entrypoint.
• minestom-mcp-server remains available as a secondary installed command alias.
• npm npx resolves the matching bin when one of the bin entries matches the package name, so publishing the package as minestom-mcp with a minestom-mcp bin keeps npx -y minestom-mcp 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.

Community and contribution docs live in CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.

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 dev
pnpm lint:fix
pnpm check

Husky installs local hooks during pnpm install. Commits run lint-staged, and pushes run the full pnpm check verification flow.

Publish

The package is set up for npm publishing with:

• executable bins for minestom-mcp and minestom-mcp-server
• a shebang-included bundled entrypoint in dist/server.js
• files whitelisting for the publish tarball
• a repo-local .npmrc that targets the npm registry and keeps publishes public by default
• prepack and prepublishOnly verification hooks
• GitHub Actions publishing from .github/workflows/npm-publish.yml via pnpm install/check steps and npm trusted publishing
• publishConfig.access = public

Recommended release flow:

pnpm check
npm pack --dry-run
npm publish

For npm trusted publishing, configure npm to trust the workflow filename npm-publish.yml in .github/workflows/. The workflow uses pnpm for dependency installation and verification, then publishes minestom-mcp with npm publish through GitHub Actions OIDC instead of a long-lived NPM_TOKEN.