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.

Servidores relacionados

Scout Monitoring MCP

patrocinador

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

Alpha Vantage MCP Server

patrocinador

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

CAD-Query MCP Server

A server for generating and verifying CAD models using the CAD-Query Python library.

Remote MCP Server (Authless)

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

Jetty.io

Work on dataset metadata with MLCommons Croissant validation and creation.

Hashnode MCP Server

An MCP server for interacting with the Hashnode API.

AST2LLM for Go

A local AST-powered context enhancement tool for LLMs that analyzes Go project structure for faster context resolution.

Memory Bank MCP

An AI-assisted development plugin that maintains persistent project context using structured markdown files for goals, decisions, and progress.

Google Workspace Developers

Developer documentation for Google Workspace APIs

Software Planning Tool

Facilitates software development planning through an interactive and structured approach.

Matter AI

Provides advanced code review, implementation planning, and pull request generation using Matter AI.

Just Prompt

A unified interface for various Large Language Model (LLM) providers, including OpenAI, Anthropic, Google Gemini, Groq, DeepSeek, and Ollama.