Getting Started

Getting Started

1. Install

No external Python dependencies (pyproject.toml has none). You need Python 3.10+ on your PATH.

Two ways to run it, matching the two options in README.md:

• npx -y @britakee/modhelper-mcp - if published to npm, your IDE launches it fresh each time, no local install needed.
• python -m modhelper_mcp.server run from inside this folder - no install step at all, just point your IDE's cwd here.

Windows note: don't use the .sh files under scripts/ or bin/ directly from PowerShell; they're Unix shell scripts. Use the python -m form instead (see IDE Configuration).

2. Get your API keys

Platform	Required?	Where
CurseForge	Yes, for any curseforge_* tool	console.curseforge.com → API Keys
Modrinth	No (only for higher rate limits)	Modrinth account settings → Personal Access Tokens. Scopes needed: Read projects, Read versions only.
Nexus Mods	Only if you enable the nexus group	Nexus account → API Access
Thunderstore	No	Optional bearer token, public API otherwise
Steam	Only if you enable the steam group	Steam Web API key

Nothing hard-fails at startup if a key is missing. Each platform's tools raise a clear error only when you actually try to call them without the key they need.

3. Understand the group system

Every tool is disabled by default. You turn on entire groups (or individual tool names) via one environment variable:

MODHELPER_MCP_ENABLED_TOOLS=modrinth,curseforge,knowledge,git

The 9 groups: modrinth, curseforge, nexus, thunderstore, steam, git, docs, dev, knowledge, automation (10 listed here because docs and knowledge are separate groups despite both being documentation-related - see Tool Groups for what's actually in each).

Start narrow. If you're only doing Minecraft mod research and downloads:

MODHELPER_MCP_ENABLED_TOOLS=modrinth,curseforge

Add git when you want the source-repo identification/clone-command tools. Add automation only when you actually have a MineFlayer bot connection to control - it's a large group (25 tools) that does nothing useful without a running bot.

You can also exclude specific tools from an otherwise-enabled group with a second environment variable:

MODHELPER_MCP_ENABLED_TOOLS=curseforge,modrinth
MODHELPER_MCP_DISABLED_TOOLS=curseforge_download_with_dependencies

MODHELPER_MCP_DISABLED_TOOLS accepts group names (removes the whole group) or exact tool names (removes just that one), same comma-separated format as the enable list.

4. Confirm it's working

After configuring your IDE (next doc), ask your agent to list available tools from modhelper-mcp. You should see only the tools from the groups you enabled, not all 81. Then run one real call per platform you enabled (e.g. modrinth_search needs no key, curseforge_search_mods confirms your CurseForge key) before relying on it for real work.