maven-indexer-mcp

一个模型上下文协议（MCP）服务器，用于索引本地Maven仓库（~/.m2/repository）和Gradle缓存（~/.gradle/caches/modules-2/files-2.1），为AI代理提供搜索Java类、方法签名和源代码的工具。

GitHub

试用此 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

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.

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.

CLI alternative

Install globally for direct terminal usage:

npm install -g maven-indexer-cli

Then use maven-indexer-cli explore ... or any of the CLI commands directly.

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

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.

Your first prompt

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

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

Your MCP client 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 coordinate (groupId, artifactId, keyword). 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.