Troubleshooting

Troubleshooting

"No tools available" / empty tool list

Check MODHELPER_MCP_ENABLED_TOOLS is actually set in your IDE's config env block. If it's missing or empty, the server intentionally clears its entire tool registry at startup rather than silently exposing all 81 - this is expected behavior, not a bug, but it means a typo'd or forgotten env var looks identical to "server didn't start."

"Missing CURSEFORGE_API_KEY" when calling any curseforge_* tool

CurseForge tools require a key for every call, no exceptions - unlike Modrinth, which works fully anonymously. Get one from console.curseforge.com and add it to your config's env block, then restart your IDE (env changes aren't picked up live).

A tool I expect isn't showing up even though I enabled its group

Double check the group name spelling against Tool Groups - it's an exact string match against TOOL_GROUPS keys in server.py, no fuzzy matching. Also check MODHELPER_MCP_DISABLED_TOOLS isn't accidentally excluding it - that variable is applied after the enabled list, so it can silently remove something you thought you'd enabled.

chmod: command not found on Windows

You're trying to run one of the .sh files under scripts/ or bin/ directly in PowerShell - those don't work on Windows at all. Use python -m modhelper_mcp.server as your IDE's command/args instead (see IDE Configuration).

Modrinth calls return 429 / rate limited

Add MODRINTH_API_KEY (a Personal Access Token with only Read projects and Read versions scopes) to raise your rate limit. Public anonymous access is intentionally rate-limited more aggressively by Modrinth itself.

clone_source_reference / download_mdk_template fail with a git error

These shell out to git clone under the hood. Confirm git is on your system PATH and that you have network access to github.com from wherever the MCP process actually runs (not necessarily the same machine/network context as your IDE, if you're using a remote agent environment).

Updating a mod left two jars installed instead of one

You called download_file without replace_existing: true. Re-run with that flag set, pointed at the same output_dir the old copy lives in - it looks up the previous download for that same mod/project id (tracked in a .mcp-manifest.json file in that folder) and removes it before writing the new one. If the old jar was installed manually (not through this MCP), there's no tracked entry to find - remove it yourself first.

knowledge group tools return nothing / "no results"

These are local SQLite lookups, not live API calls - they only work if the Parchment mappings / canonical mod examples database has actually been indexed first via the separate mcmodding-mcp indexer. An empty result here usually means the index hasn't been built yet, not that the tool is broken.

automation (MineFlayer) tools time out or refuse to connect

Confirm Node.js is installed and the MineFlayer npm packages this group depends on are actually present, and that bot_connect is targeting a server that's actually running and reachable. This group does nothing useful without a live bot connection - if you're not actively testing in-game behavior, leave it disabled entirely rather than debugging it.