Quarkus MCP Servers

Quarkus-based MCP servers for interacting with JDBC databases, filesystems, and Docker containers.

Quarkus MCP Servers

Server MCP (Model Context Protocol) universali basati su Quarkus. Supporta database JDBC, filesystem, container Docker e molto altro con un singolo JAR.

🚀 Setup Rapido

1. Setup JDK 17

Il progetto richiede JDK 17. Usa lo script automatico per scaricarlo e configurarlo:

# Setup automatico JDK 17
./setup-jdk17.sh

Lo script:

Rileva automaticamente l'architettura (x64, aarch64) e OS (Linux, macOS)
Scarica JDK 17 da Eclipse Temurin
Configura le variabili d'ambiente JAVA_HOME e PATH
Crea un file di configurazione jdk17/jdk-env.sh per riutilizzi futuri

Dopo l'installazione, carica l'ambiente JDK:

source jdk17/jdk-env.sh

2. Compilazione

Una volta configurato JDK 17, compila il progetto:

# Compila tutti i moduli (senza test per velocità)
./build-no-tests.sh

Il comando creerà i JAR in:

jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar - Server JDBC
filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar - Server Filesystem
containers/target/mcp-server-containers-999-SNAPSHOT.jar - Server Container
jvminsight/target/mcp-server-jvminsight-999-SNAPSHOT.jar - Server JVM Insights

🐳 Utilizzo con Docker

Build immagine Docker

# Builda l'immagine Docker con tutti i server
./docker-mcp.sh build

Server JDBC

# Oracle (richiede Oracle su localhost:1521)
./docker-mcp.sh oracle

# Oracle in modalità read-only (solo lettura)
./docker-mcp.sh run jdbc --jdbc.url="jdbc:oracle:thin:@localhost:1521:xe" --jdbc.user="ORACLEUSR" --jdbc.password="ORACLEUSR" --jdbc.readonly=true

# H2 in memoria
./docker-mcp.sh h2

# Server JDBC generico
./docker-mcp.sh run jdbc --jdbc.url="jdbc:postgresql://localhost:5432/mydb" --jdbc.user="user" --jdbc.password="pass"

# MySQL in modalità read-only
./docker-mcp.sh run jdbc --jdbc.url="jdbc:mysql://localhost:3306/mydb" --jdbc.user="root" --jdbc.password="toor" --jdbc.readonly=true

# PostgreSQL in modalità read-only
./docker-mcp.sh run jdbc --jdbc.url="jdbc:postgresql://localhost:5432/mydb" --jdbc.user="postgres" --jdbc.password="postgres" --jdbc.readonly=true

# Server JDBC in modalità read-only
./docker-mcp.sh run jdbc --jdbc.url="jdbc:postgresql://localhost:5432/mydb" --jdbc.user="user" --jdbc.password="pass" --jdbc.readonly=true

Server Filesystem

# Monta /tmp come directory condivisa
./docker-mcp.sh filesystem /tmp

# Directory personalizzata
./docker-mcp.sh filesystem /path/to/directory

Altri server

# Container Docker
./docker-mcp.sh run containers

# JVM Insights
./docker-mcp.sh run jvminsight

⚙️ Configurazione MCP

Generazione automatica

Genera automaticamente la configurazione MCP per Claude Desktop:

./docker-mcp.sh config

Questo crea il file mcp-docker-config.json con configurazioni per:

Server JDBC Oracle
Server JDBC H2
Server Filesystem
Server Container
Server JVM Insights

Configurazione manuale per Claude Desktop

Linux/macOS

Copia il contenuto del file generato in:

~/.config/claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

Configurazione per Docker

Esempio configurazione Docker:

{
  "mcpServers": {
    "jdbc-oracle-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "mcp-servers:latest", "jdbc",
        "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
        "--jdbc.user=ORACLEUSR",
        "--jdbc.password=ORACLEUSR",
        "--jdbc.readonly=false"
      ]
    },
    "jdbc-oracle-readonly": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "mcp-servers:latest", "jdbc",
        "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
        "--jdbc.user=ORACLEUSR",
        "--jdbc.password=ORACLEUSR",
        "--jdbc.readonly=true"
      ]
    },
    "jdbc-h2-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-p", "3000:3000",
        "mcp-servers:latest", "jdbc",
        "--jdbc.url=jdbc:h2:mem:testdb",
        "--jdbc.user=sa",
        "--jdbc.password=",
        "--jdbc.readonly=false"
      ]
    },
    "jdbc-mysql-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network",
        "host",
        "mcp-servers:latest",
        "jdbc",
        "--jdbc.url=jdbc:mysql://localhost:3306/mydb",
        "--jdbc.user=root",
        "--jdbc.password=toor",
        "--jdbc.readonly=true"
      ]
    },
    "jdbc-postgres-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network",
        "host",
        "mcp-servers:latest",
        "jdbc",
        "--jdbc.url=jdbc:postgresql://localhost:5432/mydb",
        "--jdbc.user=postgres",
        "--jdbc.password=postgres",
        "--jdbc.readonly=true"
      ]
    },
    "filesystem-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-v", "/tmp:/mnt/shared",
        "mcp-servers:latest", "filesystem", "/mnt/shared"
      ]
    }
  }
}

Configurazione per Esecuzione Locale (senza Docker)

Quando esegui i server localmente senza Docker, usa questa configurazione:

{
  "mcp": {
    "servers": {
      "jdbc-oracle": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
          "--jdbc.user=ORACLEUSR",
          "--jdbc.password=ORACLEUSR",
          "--jdbc.readonly=false"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-oracle-readonly": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
          "--jdbc.user=ORACLEUSR",
          "--jdbc.password=ORACLEUSR",
          "--jdbc.readonly=true"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-h2": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:h2:mem:testdb",
          "--jdbc.user=sa",
          "--jdbc.password=",
          "--jdbc.readonly=false"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-mysql": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:mysql://localhost:3306/mydb",
          "--jdbc.user=root",
          "--jdbc.password=toor",
          "--jdbc.readonly=true"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-postgres": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:postgresql://localhost:5432/mydb",
          "--jdbc.user=postgres",
          "--jdbc.password=postgres",
          "--jdbc.readonly=true"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "filesystem-local": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar",
          "/tmp"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/filesystem"
      },
      "containers-local": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/containers/target/mcp-server-containers-999-SNAPSHOT.jar"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/containers"
      }
    }
  }
}

📋 Comandi Disponibili

setup-jdk17.sh

./setup-jdk17.sh              # Setup automatico JDK 17
./setup-jdk17.sh --help       # Mostra opzioni disponibili
./setup-jdk17.sh --force      # Forza reinstallazione anche se esiste

docker-mcp.sh

./docker-mcp.sh build         # Builda immagine Docker
./docker-mcp.sh oracle        # Server JDBC Oracle
./docker-mcp.sh h2            # Server JDBC H2
./docker-mcp.sh filesystem [path]  # Server Filesystem
./docker-mcp.sh config        # Genera configurazione MCP
./docker-mcp.sh help          # Mostra aiuto

🗄️ Database Supportati

Il server JDBC supporta tutti i database con driver JDBC:

Oracle - jdbc:oracle:thin:@host:port:sid
PostgreSQL - jdbc:postgresql://host:port/database
MySQL - jdbc:mysql://host:port/database
H2 - jdbc:h2:mem:testdb (in memoria) o jdbc:h2:file:/path/to/db
SQLite - jdbc:sqlite:/path/to/database.db
SQL Server - jdbc:sqlserver://host:port;databaseName=db
MariaDB - jdbc:mariadb://host:port/database

🔒 Modalità Read-Only per Server JDBC

Il server JDBC supporta una modalità read-only che permette di esplorare e interrogare i database senza rischio di modifiche accidentali.

Funzionalità in Modalità Read-Only

✅ Operazioni Permesse:

read_query - Esecuzione di query SELECT
list_tables - Visualizzazione tabelle
describe_table - Descrizione struttura tabelle
database_info - Informazioni database (include stato read-only)

❌ Operazioni Bloccate:

write_query - INSERT, UPDATE, DELETE
create_table - Creazione tabelle

Come Attivare la Modalità Read-Only

Docker:

./docker-mcp.sh run jdbc \
  --jdbc.url="jdbc:oracle:thin:@localhost:1521:xe" \
  --jdbc.user="ORACLEUSR" \
  --jdbc.password="ORACLEUSR" \
  --jdbc.readonly=true

Esecuzione Locale:

java -jar jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar \
  --jdbc.url="jdbc:h2:mem:testdb" \
  --jdbc.user="sa" \
  --jdbc.password="" \
  --jdbc.readonly=true

Verifica Stato Read-Only

Usa il tool database_info per verificare lo stato:

{
  "database_product_name": "Oracle",
  "mcp_server_readonly_mode": "true",
  "read_only": "false",
  ...
}

Nota: mcp_server_readonly_mode indica la modalità del server MCP, mentre read_only indica se il database stesso è in sola lettura.

🔧 Esecuzione Locale (senza Docker)

Server JDBC

source jdk17/jdk-env.sh

# Modalità standard (read/write)
java -jar jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar \
  --jdbc.url="jdbc:h2:mem:testdb" \
  --jdbc.user="sa" \
  --jdbc.password="" \
  --jdbc.readonly=false

# Modalità read-only (solo lettura)
java -jar jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar \
  --jdbc.url="jdbc:h2:mem:testdb" \
  --jdbc.user="sa" \
  --jdbc.password="" \
  --jdbc.readonly=true

Server Filesystem

source jdk17/jdk-env.sh
java -jar filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar /tmp

🔍 Testing

Test server locale

# Test JDBC H2
./run-server.sh jdbc --jdbc.url="jdbc:h2:mem:testdb" --jdbc.user="sa"

# Test Filesystem
./run-server.sh filesystem /tmp

Test Docker

# Test setup Docker
./test-docker-setup.sh

📁 Struttura Progetto

quarkus-mcp-servers/
├── setup-jdk17.sh          # Setup automatico JDK 17
├── docker-mcp.sh           # Script Docker per MCP
├── build-no-tests.sh       # Build senza test
├── run-server.sh           # Esecuzione server locale
├── jdbc/                   # Server JDBC
├── filesystem/             # Server Filesystem  
├── containers/             # Server Container Docker
├── jvminsight/            # Server JVM Insights
├── jdk17/                 # JDK 17 (creato da setup)
├── mcp-configs/           # Configurazioni MCP
└── mcp-docker-config.json # Config generata per Docker

🚨 Troubleshooting

JDK 17 non trovato

# Reinstalla JDK 17
./setup-jdk17.sh --force

# Carica ambiente
source jdk17/jdk-env.sh

# Verifica versione
java -version

Docker image non trovata

# Rebuilda immagine
./docker-mcp.sh build

Errori di connessione database

Verifica che il database sia in esecuzione
Controlla URL, username e password
Per Oracle, assicurati che sia su localhost:1521

Problemi con Docker Desktop

# Su Linux, assicurati che Docker sia in esecuzione
sudo systemctl start docker

# Aggiungi utente al gruppo docker
sudo usermod -aG docker $USER
# Poi fai logout/login

📚 Documentazione Aggiuntiva

README Docker - Guida completa Docker
README Italiano - Documentazione in italiano
Standalone Java Setup - Setup Java standalone

🤝 Contributi

Fork del repository
Crea feature branch (git checkout -b feature/amazing-feature)
Commit dei cambiamenti (git commit -m 'Add amazing feature')
Push al branch (git push origin feature/amazing-feature)
Apri Pull Request

📝 Licenza

Questo progetto è sotto licenza MIT. Vedi il file LICENSE per dettagli.

Related Servers

Scout Monitoring MCP

sponsor

Put performance and error data directly in the hands of your AI assistant.

Alpha Vantage MCP Server

sponsor

Access financial market data: realtime & historical stock, ETF, options, forex, crypto, commodities, fundamentals, technical indicators, & more

GraphQL MCP Server

A strongly-typed MCP server that provides seamless access to any GraphQL API.

Packmind

Access and manage your team's coding best practices and knowledge base from Packmind.

MCP Starter Server

A minimal template for building AI assistant tools using the ModelContextProtocol.

OpenAI Image Generation

Generate and edit images using OpenAI's DALL-E models via the official Python SDK.

AIO-MCP Server

An MCP server with integrations for GitLab, Jira, Confluence, and YouTube, providing AI-powered search and development utility tools.

Remote MCP Server on Cloudflare

A customizable remote MCP server for deployment on Cloudflare Workers, operating without authentication.

Authless Remote MCP Server

An authless remote MCP server designed for deployment on Cloudflare Workers. It can be set up locally using npm create.

Remote DCInside MCP Server (Authless)

An example of a remote MCP server without authentication, deployable on Cloudflare Workers.

Agent Forge

A platform for creating and managing AI agents with specific personalities and simulating their responses. Requires a DeepSeek API key.

Openapi MCP

An MCP server that lets LLMs inspect and interact with OpenAPI specifications.