Content
# Tool List
Based on the Model Context Protocol (MCP), a universal JDBC database tool that communicates with large model agents through `stdio`, supporting command-line parameter loading, dynamic driver loading, read-only security interception, and formatted data return.
## Quick Start
### 1. Build the Project
```bash
mvn clean package
```
After building, the distribution package is located at `target/jdbc-mcp-tool.zip`.
### 2. Installation
```bash
unzip target/jdbc-mcp-tool.zip -d ~/
```
The directory structure after decompression:
```
jdbc-mcp-tool/
├── jdbc-mcp.jar # Simplified JAR (only containing project business logic)
├── driver/ # Database drivers placed by users
│ └── <user-added JDBC drivers>
├── lib/ # Runtime dependencies (managed by MANIFEST.MF)
│ ├── mcp-*.jar
│ ├── slf4j-api-*.jar
│ ├── logback-classic-*.jar
│ ├── logback-core-*.jar
│ └── jackson-*.jar
└── logs/ # Log directory (automatically created at runtime)
```
### 3. Prepare Startup Parameters
This tool no longer reads `config.yml`; all database connection parameters are passed through the command line:
```bash
java -jar jdbc-mcp.jar \
--driver-class com.mysql.cj.jdbc.Driver \
--url "jdbc:mysql://127.0.0.1:3306/my_db?useSSL=false" \
--username read_user \
--password secure_password \
--max-rows 50
```
Parameters support both registered short commands and `--key=value` notation, for example: `-d com.mysql.cj.jdbc.Driver` or `--driver-class=com.mysql.cj.jdbc.Driver`.
Write operations are prohibited by default; to allow `execute_update` to execute modification statements, explicitly append the boolean switch `--danger-allow-write` (this switch does not require a parameter value).
### 4. Place JDBC Drivers
Place the database driver JAR file in the `driver/` directory, for example:
```bash
cp mysql-connector-j-8.x.jar ~/jdbc-mcp-tool/driver/
```
### 5. Configure MCP Client
This tool communicates with the MCP client through `stdio`, using **Claude Code** as an example to illustrate the configuration method.
#### Claude Code
Create a `.mcp.json` file in the project root directory:
```json
{
"mcpServers": {
"jdbc-mcp": {
"type": "stdio",
"command": "java",
"args": [
"-jar",
"/path/to/jdbc-mcp-tool/jdbc-mcp.jar",
"--driver-class", "com.mysql.cj.jdbc.Driver",
"--url", "jdbc:mysql://127.0.0.1:3306/my_db?useSSL=false",
"--username", "read_user",
"--password", "secure_password",
"--max-rows", "50"
]
}
}
}
```
> **Note**: Replace `/path/to/jdbc-mcp-tool/` with the actual installation path and fill in the parameters according to the actual database connection information.
After configuration, Claude Code will automatically load the MCP server, and the database tool can be used in the conversation.
#### Development Mode
During development, you can use the project's built-in `run.sh` script (automatically compile and splice classpath):
```json
{
"mcpServers": {
"jdbc-mcp": {
"type": "stdio",
"command": "./run.sh",
"args": [
"--driver-class", "com.mysql.cj.jdbc.Driver",
"--url", "jdbc:mysql://127.0.0.1:3306/my_db?useSSL=false",
"--username", "read_user",
"--password", "secure_password",
"--max-rows", "50"
]
}
}
}
```
## MCP Tool Description
This tool registers the following 6 MCP tools with the Agent:
### Metadata Exploration
| Tool | Description |
|------|------|
| `list_catalogs` | List all catalogs |
| `list_schemas` | List schemas, filterable by catalog |
| `list_tables` | List tables and views, filterable by catalog/schema/table name |
| `get_table_schema` | Get column metadata (type, length, nullable, primary key, auto-increment, etc.) for a specified table |
### Data Operations
| Tool | Description |
|------|------|
| `execute_query` | Execute read-only query SQL (SELECT), naturally read-only, return Markdown format results, limited by `--max-rows` |
| `execute_update` | Execute data modification SQL (INSERT/UPDATE/DELETE/DDL), return affected rows. Prohibited by default in read-only mode; explicitly specify `--danger-allow-write` to allow write operations |
#### execute_query Output Example
The output is divided into `# Schema` (column name, type, length) and `# Data` (data rows), with NULL values rendered as `<i>NULL</i>`.
```markdown
# Schema
| Name | Type | Length |
| --- | --- | --- |
| user_id | VARCHAR | 64 |
| age | INT | 11 |
# Data
| user_id | age |
| --- | --- |
| USR_001 | 28 |
| USR_002 | <i>NULL</i> |
```
## Command Line Parameter Specification
| Long Option | Short Option | Description | Required | Default Value |
|--------|--------|------|------|--------|
| `--driver-class` | `-d` | JDBC driver fully qualified class name | Yes | - |
| `--url` | - | JDBC connection URL | Yes | - |
| `--username` | `-u` | Database username | Yes | - |
| `--password` | `-p` | Database password | Yes | - |
| `--danger-allow-write` | - | Whether to allow write operations; boolean switch, no parameter value required | No | `false` |
| `--max-rows` | `-m` | Maximum returned rows for query results (affects `execute_query`) | No | `100` |
