Maven Indexer Mcp

Maven Index

An MCP server and CLI that indexes your local Maven repository (~/.m2/repository) and Gradle cache (~/.gradle/caches/modules-2/files-2.1) to provide AI agents with tools to search for Java classes, method signatures, and source code — even for internal company packages and non-well-known public libraries.

Quick Install

There are two ways to give an agent access to the index. Pick one, or use both:

• CLI + Agent Skill: for terminal coding agents (Claude Code, Codex, Gemini CLI, OpenCode, Cursor). The agent runs maven-indexer-cli commands, guided by the maven-indexer skill. No tool schemas sit in the context window, so it uses fewer tokens.
• MCP server: for IDE-integrated agents (Cursor, Kiro, Windsurf, JetBrains, ...). See MCP server.

CLI + Agent Skill

Install script (recommended)

One command installs maven-indexer-cli from npm and the maven-indexer skill for every coding agent it detects:

curl -fsSL https://raw.githubusercontent.com/tangcent/maven-indexer-mcp/main/install.sh | bash

Requires Node.js 18+ and npm. Pass options after bash -s --:

curl -fsSL https://raw.githubusercontent.com/tangcent/maven-indexer-mcp/main/install.sh | bash -s -- --target claude,agents --index

Option	Meaning
--target <t>	Which agents get the skill: auto (detected agents, default), all, or a csv of claude, agents, cursor (see the skill directories).
--location <l>	global (home directory, default) or local (current project).
--dir <path>	Install the skill into this skills directory instead.
--version <v>	maven-indexer-cli version to install (default latest).
--skip-cli / --skip-skills	Install only the skill / only the CLI.
--index	Build the index right after installing.

Re-running the script upgrades both the CLI and the skill. Restart your agent (or start a new session) afterwards so it loads the skill.

Manual install: maven-indexer-cli

npm install -g maven-indexer-cli
maven-indexer-cli refresh-index   # build the index once; later runs use `maven-indexer-cli sync`

Or run it without installing: npx -y maven-indexer-cli <command>.

Install the skill with maven-indexer-cli

Once the CLI is installed, it can install the skill it ships with:

maven-indexer-cli skills install                          # every detected agent, global
maven-indexer-cli skills install --target claude,agents   # pick agents
maven-indexer-cli skills install --location local         # into the current project (.claude/skills, ...)
maven-indexer-cli skills install --dir ~/my-agent/skills  # any skills directory
maven-indexer-cli skills status                           # installed / stale / missing per agent
maven-indexer-cli skills uninstall

skills install is idempotent: run it again after upgrading the CLI to update the skill. Add --dry-run to preview the files it writes. It never overwrites a different skill that happens to use the maven-indexer directory name.

Manual install: the skill

The skill is a single file, skills/maven-indexer/SKILL.md. Copy it into a maven-indexer folder under your agent's skills directory, for example for Claude Code:

mkdir -p ~/.claude/skills/maven-indexer
curl -fsSL https://raw.githubusercontent.com/tangcent/maven-indexer-mcp/main/skills/maven-indexer/SKILL.md -o ~/.claude/skills/maven-indexer/SKILL.md

Skill directories

Target	Agents	Global	Local (project)
claude	Claude Code	~/.claude/skills/	.claude/skills/
agents	Codex, Gemini CLI, OpenCode and other clients that read the shared Agent Skills folder	~/.agents/skills/	.agents/skills/
cursor	Cursor	~/.cursor/skills/	.cursor/skills/

auto picks every target whose agent folder exists (~/.claude; ~/.agents, ~/.codex, ~/.gemini or ~/.config/opencode; ~/.cursor), and falls back to claude when none does.

MCP server

Add the following config to your MCP client:

{
  "mcpServers": {
    "maven-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "maven-indexer-mcp@latest"
      ]
    }
  }
}

This will automatically download and run the latest version of the server. It will auto-detect your Maven repository location (usually ~/.m2/repository) and Gradle cache.

maven-indexer-cli install can also write this entry (plus a short instructions block) into the config files of Claude Code, Cursor, Codex, OpenCode, Gemini CLI and Windsurf; run maven-indexer-cli install --help for its options.

MCP Client configuration

Cline

Follow Cline's MCP guide and use the config provided above.

Codex

Follow the configure MCP guide using the standard config from above.

Cursor

Click the button to install:

Or install manually:

Go to Cursor Settings -> MCP -> New MCP Server. Use the config provided above.

JetBrains AI Assistant & Junie

Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add. Use the config provided above. The same way maven-indexer can be configured for JetBrains Junie in Settings | Tools | Junie | MCP Settings ->Add. Use the config provided above.

Kiro

In Kiro Settings, go to Configure MCP > Open Workspace or User MCP Config > Use the configuration snippet provided above.

Or, from the IDE Activity Bar > Kiro > MCP Servers > Click Open MCP Config. Use the configuration snippet provided above.

Qoder

In Qoder Settings, go to MCP Server > + Add > Use the configuration snippet provided above.

Alternatively, follow the MCP guide and use the standard config from above.

Trae

Go to Settings -> MCP -> + Add -> Add Manually to add an MCP Server. Use the config provided above.

Windsurf

Follow the configure MCP guide using the standard config from above.

Upgrading from maven-indexer-mcp 1.0.x

Breaking change: tool names changed, and only explore is registered by default.

After upgrading, agents that call the old names get "tool not found" until you opt back in:

1.0.x tool	Now
get_class_details	get_class
search_classes	search
search_artifacts	search_artifacts
search_implementations	implementations
refresh_index	removed (the index auto-syncs; use maven-indexer-cli refresh-index)
everything else	same name, but not registered by default

To restore the full surface, set:

MAVEN_INDEXER_MCP_TOOLS=   # empty-but-set enables ALL tools

or list the ones you want: MAVEN_INDEXER_MCP_TOOLS=search,get_class,callers.

Everything else is unchanged — the published package name is still maven-indexer-mcp (the repository was renamed to maven-index), and the CLI runs through the maven-indexer-cli binary.

Your first prompt

Enter the following prompt in your agent to check if everything is working:

Find the class `StringUtils` in my local maven repository and show me its methods.

Your agent should read the class StringUtils from your local Maven repository and show its methods.

Configuration (Optional)

If the auto-detection fails, or if you want to filter which packages are indexed, you can add environment variables to the configuration:

• MAVEN_REPO: Absolute path to your local Maven repository (e.g., /Users/yourname/.m2/repository). Use this if your repository is in a non-standard location.
• GRADLE_REPO_PATH: Absolute path to your Gradle cache (e.g., /Users/yourname/.gradle/caches/modules-2/files-2.1).
• INCLUDED_PACKAGES: Comma-separated list of package patterns to index (e.g., com.mycompany.*,org.example.*). Default is * (index everything). Append ! to an entry to force-include it, overriding EXCLUDED_PACKAGES (e.g. org.springframework.security.web!).
• EXCLUDED_PACKAGES: Comma-separated list of package-prefix patterns to skip at index time (e.g. java.*,javax.*,sun.*). Default is empty (index everything). Takes precedence over INCLUDED_PACKAGES, except for force-include (!) entries. Recommended default: java.*,javax.*,sun.*,jdk.internal.*,org.omg.*. Excluding org.springframework.* is a trade-off (smaller index vs. losing Spring-internal queries) — leave Spring indexed unless index size is a concern.
• MAVEN_INDEXER_CFR_PATH: (Optional) Absolute path to a specific CFR decompiler JAR. If not provided, the server will attempt to use its bundled CFR version.
• VERSION_RESOLUTION_STRATEGY: (Optional) Strategy to choose the version when multiple versions of an artifact are found and no specific coordinate is provided.
  • semver: (Default) Prefer the highest semantic version (e.g. 1.2.0 > 1.1.9).
  • latest-published: Prefer the version with the latest publish time (checks *.pom.lastUpdated first, then file modification time).
  • latest-used: Prefer the version most recently imported/used by the user (based on file creation time).

Example with optional configuration:

{
  "mcpServers": {
    "maven-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "maven-indexer-mcp@latest"
      ],
      "env": {
        "MAVEN_REPO": "/Users/yourname/.m2/repository",
        "GRADLE_REPO_PATH": "/Users/yourname/.gradle/caches/modules-2/files-2.1",
        "INCLUDED_PACKAGES": "com.mycompany.*",
        "MAVEN_INDEXER_CFR_PATH": "/path/to/cfr-0.152.jar",
        "VERSION_RESOLUTION_STRATEGY": "semver"
      }
    }
  }
}

Available Tools

By default only explore is registered — it covers almost every question in a single call. The other 16 tools below are defined but only registered when you opt in via MAVEN_INDEXER_MCP_TOOLS (see Narrow Tools).

explore (PRIMARY — default-registered)

• explore: PRIMARY tool — call FIRST for almost any question about a class, dependency, or call flow in the local Maven/Gradle artifact cache. Returns class source/signatures + implementations + callers/callees + call path in ONE capped response. Answers "how does this work / where is this used?" in a single call. Registered by default (no opt-in needed).
  • Input:
    • identifiers (string[], required): bag of names — class names (FQCN or simple), coordinates (groupId:artifactId[:version]), method targets (Class.method), or resource paths.
    • coordinate (string, optional): pin the artifact version for all class/method identifiers (groupId:artifactId:version).
    • include (string[], optional): sections to populate. Omit for the default (signatures, implementations, callers, callees). Vocabulary: source, signatures, implementations, callers, callees, path, resources, dependencies, dependents.
    • maxLines (number, optional): line budget (default 200).
    • question (string, optional): natural-language question; used as a fallback when no identifier resolves (search-candidates mode).
    • projectPath (string, REQUIRED for MCP; optional for CLI — defaults to cwd): absolute path to the project root. MCP servers launch globally with an unreliable cwd, so state the project explicitly to pin version resolution to your project's dependencies.
  • Output: composed, line-capped text with the requested sections.

Narrow Tools (opt-in via MAVEN_INDEXER_MCP_TOOLS)

These 16 narrow tools are defined but NOT registered by default — explore already covers the same ground in one call. Register them only when you need a specific slice.

• Set MAVEN_INDEXER_MCP_TOOLS=search,get_class,callers to enable specific tools (CSV of short names).
• Set MAVEN_INDEXER_MCP_TOOLS= (empty-but-set) to enable ALL narrow tools (escape hatch — useful for tests and batch scripts).
• explore is always registered regardless of this setting.

Each tool below names explore as the preferred alternative.

• search: Search for Java classes by name (FQCN, partial, or keyword). Replaces search_classes. Prefer explore (pass class names in identifiers).
• get_class: Retrieve source code or signatures for a class. Supports batch. Replaces get_class_details. Prefer explore with include: ["source"] or ["signatures"].
• get_resource: Retrieve a single text resource (proto, XML, properties) from a JAR. Prefer explore with include: ["resources"].
• implementations: Search for classes that implement/extend a given interface/class. Prefer explore with include: ["implementations"].
• callers: List methods that invoke the given class/method (call-graph). Prefer explore with include: ["callers"].
• callees: List methods invoked by the given class/method (call-graph). Prefer explore with include: ["callees"].
• impact: Transitive impact (callers-of-callers) via BFS up the call graph. Prefer explore (which surfaces direct callers/callees in one call).
• dependencies: List the parsed Maven <dependencies> of an artifact. Replaces get_dependencies. Prefer explore with include: ["dependencies"].
• dependents: Find indexed artifacts that depend on the given coordinate. Replaces find_dependents. Prefer explore with include: ["dependents"].
• info: Get artifact info (path, layout, class count, resource count). Prefer explore with include: ["path"].
• stats: Aggregate index statistics (artifact count, class count, db size). Prefer explore (no direct equivalent; use stats for raw counts).
• list_classes: List all distinct Java/protobuf class names indexed for a specific artifact coordinate. Prefer explore (pass the coordinate in identifiers).
• project_context: Inspect the active project's Maven/Gradle context (declared/resolved dependency tree, build file, project coordinate). Useful when version resolution surprises you. Takes required projectPath. Prefer explore (pass projectPath).
• search_artifacts: Search for artifacts by groupId, artifactId, keyword, or an exact groupId:artifactId[:version] coordinate; newest versions are listed first. Supports batch. Prefer explore (pass coordinates in identifiers).
• search_resources: Search for text resources inside JARs (proto, XML, properties). Prefer explore with include: ["resources"].
• search_methods: Search for Java methods by name across indexed artifacts. Prefer explore (pass Class.method in identifiers).

Note: The doctor command (check indexed artifacts for missing JARs on disk) is CLI-only — there is no MCP equivalent.

Note: The sync command (fast incremental refresh via mtime) is CLI-only. MCP has its own background watcher that re-indexes on filesystem changes, so a manual sync is unnecessary when the watcher is active.

Maven Indexer MCP vs Maven Indexer CLI

This repository hosts both packages. Pick the face that matches your workflow:

• CLI (maven-indexer-cli): Modern coding agents increasingly favor CLI-based workflows exposed as SKILLs over MCP because CLI invocations are more token-efficient: they avoid loading large tool schemas into the model context, allowing agents to act through concise, purpose-built commands. This makes CLI + SKILLs better suited for high-throughput coding agents that must balance dependency lookups with large codebases and reasoning within limited context windows.
  Learn more about Maven Indexer CLI with SKILLS.

• MCP (maven-indexer-mcp): MCP remains the better choice for IDE-integrated agents (Cursor, Kiro, Windsurf, etc.) that benefit from persistent background indexing, automatic repository watching, and seamless tool invocation without any CLI setup. The MCP server indexes your repository in the background and keeps the index up to date automatically.

Local Development

If you prefer to run from source:

1. Clone the repository:

   git clone https://github.com/tangcent/maven-indexer-mcp.git
   cd maven-indexer-mcp
   

2. Install dependencies and build:

   npm install
   npm run build
   

3. Use the absolute path in your config:

   {
     "mcpServers": {
       "maven-indexer": {
         "command": "node",
         "args": ["/absolute/path/to/maven-indexer-mcp/build/index.js"]
       }
     }
   }
   

• Run tests: npm test
• Watch mode: npm run watch

Repository

This repository was renamed from maven-indexer-mcp to maven-index as part of the engine unification (one engine, two thin faces). The standalone maven-indexer-cli git repo is deprecated — its npm package is now published from this repo's workspace.

Path	Published as	Description
packages/engine	@maven-indexer/engine (private, internal)	The shared engine: Indexer, parsers, schema, resolver, explore(), project_context
packages/cli	maven-indexer-cli	Commander.js CLI face — thin; imports engine
packages/mcp	maven-indexer-mcp	MCP SDK server face — thin; imports engine

Both published packages (maven-indexer-cli, maven-indexer-mcp) keep their names and bin entries unchanged for backward compatibility — existing npx -y maven-indexer-mcp@latest and npm install -g maven-indexer-cli invocations keep working.

License

ISC