quarkus-agent

Quarkus Agent MCP

A standalone MCP server that enables AI coding agents to create, manage, and interact with Quarkus applications. It runs as a separate process that survives app crashes, giving agents the ability to create projects, check for updates, read extension skills, control application lifecycle, proxy Dev MCP tools, and search Quarkus documentation.

Part of the DevStar working group.

Prerequisites

• Java 21+
• Docker or Podman (for documentation search)
• One of: Quarkus CLI, Maven, or JBang (for creating new projects)

Installation

Claude Code plugin

Add the marketplace and install the plugin:

claude plugin marketplace add quarkusio/quarkus-agent-mcp
claude plugin install quarkus-agent@quarkus-tools

This installs the plugin and configures the MCP server automatically. Requires JBang.

Via JBang (recommended)

JBang resolves the uber-jar from Maven Central automatically — no build step needed.

Claude Code

claude mcp add quarkus-agent -- jbang quarkus-agent-mcp@quarkusio

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "quarkus-agent": {
      "type": "stdio",
      "command": "jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

IBM Bob

Add to .bob/mcp.json:

{
  "mcpServers": {
    "quarkus-agent": {
      "command": "jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "quarkus-agent": {
      "command": "jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "quarkus-agent": {
      "command": "jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

JetBrains IDEs (IntelliJ IDEA, WebStorm, etc.)

In Settings → Tools → AI Assistant → MCP Servers (or the GitHub Copilot MCP settings), add a server with an absolute path to jbang:

{
  "mcpServers": {
    "quarkus-agent": {
      "type": "stdio",
      "command": "/home/you/.jbang/bin/jbang",
      "args": ["quarkus-agent-mcp@quarkusio"]
    }
  }
}

Why absolute paths? JetBrains IDEs launched from the desktop inherit the system PATH, not your shell PATH (~/.bashrc / ~/.zshrc). Tools installed via SDKMAN!, JBang's default installer, asdf, or mise are typically on the shell PATH only — so the IDE can't find them. See Troubleshooting below.

Alternatively, use the direct download method with an absolute path to java:

{
  "mcpServers": {
    "quarkus-agent": {
      "type": "stdio",
      "command": "/path/to/java",
      "args": ["-jar", "/path/to/quarkus-agent-mcp-runner.jar"]
    }
  }
}

Via direct download

Download the uber-jar from the latest GitHub Release, then:

claude mcp add quarkus-agent -- java -jar /path/to/quarkus-agent-mcp-runner.jar

Build from source

git clone https://github.com/quarkusio/quarkus-agent-mcp.git
cd quarkus-agent-mcp
./mvnw package -DskipTests -Dquarkus.package.jar.type=uber-jar

This produces the uber-jar at target/quarkus-agent-mcp-1.0.0-SNAPSHOT-runner.jar (version may vary).

claude mcp add quarkus-agent -- java -jar /path/to/quarkus-agent-mcp/target/quarkus-agent-mcp-1.1.3-runner.jar

Verify

After registering, ask your agent something like:

"Search the Quarkus docs for how to create a REST endpoint"

If the MCP server is working, the agent will use quarkus_searchDocs and return documentation results.

Usage

Creating a new Quarkus app

Ask your agent to build a Quarkus application using natural language. The agent uses the MCP tools automatically.

Example conversation: