maven-mcp

Agent plugin for Claude Code, Grok Build, Cursor, and Codex that provides Maven dependency intelligence via an MCP server — query artifact versions, scan projects for outdated dependencies, check for vulnerabilities, and fetch changelogs.

How it works

The plugin bundles a single-file Python 3 MCP server (plugin/server/server.py) that speaks MCP over stdio (JSON-RPC 2.0 on stdin/stdout) or over a stateless Streamable HTTP endpoint. It uses the Python standard library only — zero pip dependencies. The plugin registers the server via .mcp.json (Claude Code, Grok Build) and mcp.json (Cursor, Codex), both command: python3, so it installs with no extra runtime setup. The server can also be run standalone and connected to any MCP-compatible agent — see Use with any MCP client.

Version lookups use the repositories the build file declares. Maven Central, Google Maven, and the Gradle Plugin Portal are used when that scope declares none. Private repositories need credentials — see Configuration.

Gradle scanning runs the project's wrapper once and reads production runtime classpaths (*RuntimeClasspath), then merges declared provenance from build files and version catalogs. Maven scanning reads pom.xml locally.

Tools

Skills

Claude Code keeps a listing of every installed skill's name and description in context, on a budget of ~1% of the model's context window; when the listing overflows, descriptions get dropped. Twenty-two entries from one plugin consume that budget on their own, so only the skills whose body adds a workflow beyond a single tool call stay model-routed. The rest are manual: the slash command and the underlying MCP tool are unchanged, Claude just no longer carries their descriptions in every session.

Model-routed — Claude picks these up on its own, and you can also invoke them by name:

Manual only (disable-model-invocation: true) — invoke by name; Claude reaches the same capability through the MCP tool above:

Supported build systems

• Gradle — build.gradle, build.gradle.kts, settings.gradle, settings.gradle.kts
• Maven — pom.xml
• Version catalogs — gradle/libs.versions.toml

Requirements

• Python 3.9+ — the server uses the standard library only; no pip dependencies.
• jq and timeout / gtimeout — used by the write-time hooks. On macOS, timeout comes from brew install coreutils (gtimeout). Without them the hooks do nothing and the edit proceeds. The MCP server itself does not need either.

Configuration

Cache location, private-repo credentials, mirrors, TLS, and the rest of the variables: docs/configuration.md.

Installation

Claude Code (marketplace)

/plugin marketplace add kirich1409/maven-mcp
/plugin install maven-mcp@maven-mcp

Grok Build (marketplace)

grok plugin marketplace add kirich1409/maven-mcp
grok plugin install maven-mcp@maven-mcp --trust

--trust is required for the bundled MCP server and write-guard hooks to run. Reload plugins (r in the Plugins tab) or start a new session after install.

Cursor and Codex (npx plugins)

npx plugins add kirich1409/maven-mcp

The plugins CLI detects installed agents and installs into each of them. plugin/ ships three manifests over the same skills/, server, and hook scripts:

There is deliberately no root plugin.json (Agent Plugins 1.0 manifest). With one present, Codex loads the package through its Agent Plugins loader, ignores .codex-plugin/plugin.json, and silently disables every hook (openai/codex#39895). It comes back once that is fixed; mcp.json already uses the Agent Plugins shape.

python3 (3.9+) must be on PATH, same as for the Claude Code plugin.

Local path (development)

# Claude Code
claude plugin marketplace add /path/to/maven-mcp
claude plugin install maven-mcp@maven-mcp

# Grok Build
grok plugin marketplace add /path/to/maven-mcp
grok plugin install maven-mcp@maven-mcp --trust

The plugin registers the bundled server via .mcp.json automatically; no separate install or build step is required.

npm, Homebrew, and an MCPB bundle are not install channels. Non-plugin clients use uv (uvx maven-mcp, or maven-mcp after uv tool install maven-mcp). uv downloads Python 3.9+; it is not preinstalled by local Claude Code, Codex, or Grok. Claude Code cloud VMs already have Python and uv. Web ChatGPT cannot spawn a local process and is HTTP-only (see below).

Use with any MCP client

Codex, Cursor, Claude Desktop, Gemini CLI, and Kimi run the published console script. The command is uvx maven-mcp (distribution name maven-mcp).

• Kimi Code — ~/.kimi-code/mcp.json (user-level) or .kimi-code/mcp.json (project-level):

  {
    "mcpServers": {
      "maven-mcp": {
        "command": "uvx",
        "args": ["maven-mcp"]
      }
    }
  }

• Cursor — ~/.cursor/mcp.json, same mcpServers shape as above.

• Claude Desktop — claude_desktop_config.json, same mcpServers shape as above.

• Gemini CLI — ~/.gemini/settings.json:

  {
    "mcpServers": {
      "maven-mcp": {
        "command": "uvx",
        "args": ["maven-mcp"]
      }
    }
  }

• Codex — ~/.codex/config.toml (Codex Desktop may ignore a project .codex/config.toml; the user-level file is the one these steps use):

  [mcp_servers.maven-mcp]
  command = "uvx"
  args = ["maven-mcp"]

Environment variables (GITHUB_TOKEN, MAVEN_MCP_OFFLINE, …) can be passed through each client's env field. Plugin installs keep python3 and ${CLAUDE_PLUGIN_ROOT}/server/server.py in .mcp.json.

HTTP mode (remote / cloud agents)

For agents that cannot spawn a local process (cloud sandboxes, remote workspaces), the server also speaks stateless Streamable HTTP. Start it once:

MAVEN_MCP_TRANSPORT=http MAVEN_MCP_HTTP_HOST=127.0.0.1 MAVEN_MCP_HTTP_PORT=8765 \
  uvx maven-mcp

The MCP endpoint is http://<host>:<port>/mcp (single POST endpoint, JSON responses, no SSE). Connect with a URL-based entry instead of command:

• Kimi Code (mcp.json): {"mcpServers": {"maven-mcp": {"url": "http://127.0.0.1:8765/mcp"}}}
• Gemini CLI (settings.json): {"mcpServers": {"maven-mcp": {"httpUrl": "http://127.0.0.1:8765/mcp"}}}
• Codex (config.toml): [mcp_servers.maven-mcp] with url = "http://127.0.0.1:8765/mcp"

MAVEN_MCP_HTTP_HOST defaults to 127.0.0.1 and MAVEN_MCP_HTTP_PORT to 8765. The HTTP transport has no authentication — bind it to localhost or a trusted network only; for exposure to cloud agents over the internet, put it behind a reverse proxy that terminates TLS and enforces auth.

Hooks

pre-edit-deps.sh runs before an edit to a Gradle, Maven, or version-catalog file. It can block a coordinate that looks hallucinated or is flagged malicious, and it can ask on a critical or high CVE, a typosquat-shaped package, or a toolchain mismatch. post-edit-deps.sh reminds you to run /check-deps. Both fail open: a missing jq, timeout/gtimeout, or a server error lets the edit through. Codex still applies apply_patch after a deny (openai/codex#27833).

Development

python3 -m unittest discover -s tests
python3 scripts/check-versions.py

Contribution branches come from develop, and the contract for coding agents is AGENTS.md. A release is a dispatch of Release on main, described in AGENTS.md.

License

MIT. See LICENSE.