Content
# Tool List
## JDBC-MCP Tool
Based on Model Context Protocol (MCP), this is a general-purpose JDBC database tool that communicates with large model agents through `stdio`, supporting multi-data source management, 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)
├── config.example.yml # Configuration template
├── config.yml # User's actual configuration (not included in version control)
├── driver/ # Database drivers placed by users
│ └── <user-added JDBC drivers>
├── lib/ # Runtime dependencies (managed by MANIFEST.MF)
│ ├── mcp-*.jar
│ ├── snakeyaml-*.jar
│ ├── slf4j-api-*.jar
│ ├── logback-classic-*.jar
│ ├── logback-core-*.jar
│ └── jackson-*.jar
└── logs/ # Log directory (automatically created at runtime)
```
### 3. Configure Data Source
Copy the configuration file from the template and edit:
```bash
cp config.example.yml config.yml
```
Edit `config.yml`:
```yaml
datasources:
- name: "my_db"
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"
read_only: true
max_rows: 50
```
### 4. Place JDBC Driver
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`. The following uses **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", "my_db"]
}
}
}
```
> **Note**: Replace `/path/to/jdbc-mcp-tool/` with the actual installation path, and `my_db` with the data source name configured in `config.yml`.
After configuration, Claude Code will automatically load the MCP server, and you can use the database tool in the conversation.
#### Development Mode
During development, you can use the project's built-in `run.sh` script (automatically compile and concatenate classpath):
```json
{
"mcpServers": {
"jdbc-mcp": {
"type": "stdio",
"command": "./run.sh",
"args": ["my_db"]
}
}
}
```
## 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, 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. Intercepted and refused in `read_only` mode |
#### execute_query Output Example
The output is divided into `# Schema` (column name, type, length) and `# Data` (data rows). NULL values are 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> |
```
## Configuration Specification
| Field | Description | Required | Default Value |
|------|------|------|--------|
| `name` | Data source name, used to specify command-line parameters | Yes | - |
| `driver_class` | Full qualified class name of JDBC driver | Yes | - |
| `url` | JDBC connection URL | Yes | - |
| `username` | Database username | Yes | - |
| `password` | Database password | Yes | - |
| `read_only` | Whether in read-only mode (affects `execute_update`) | No | `false` |
| `max_rows` | Maximum returned rows for query results (affects `execute_query`) | No | `100` |
