Turnright Database MCP Server
English | 中文
A multi-database Model Context Protocol server developed in Java that gives AI tools — Claude Code, Claude Desktop, or any MCP-compatible client — a unified interface to MySQL, SQL Server, MongoDB, Elasticsearch, Oracle and Redis, with multi-datasource support for every engine.
一个用Java开发的多数据库模型上下文协议(MCP)服务器,为AI工具(如Claude Code、Claude Desktop或任何兼容MCP的客户端)提供统一接口,支持MySQL、SQL Server、MongoDB、Elasticsearch、Oracle和Redis,并针对每种引擎提供多数据源支持。
UI配置界面:
Features
- Six engines, one protocol — 48 MCP tools covering queries, schema inspection, writes and administration.
- Multi-datasource — register several instances per engine, select one per call with the
datasourceargument, or fall back to a per-engine default. - Read-only by default — every datasource is read-only unless you explicitly set
READONLY=false; write tools are rejected before touching the database. - Two transports — stdio for locally-launched clients, Streamable HTTP (plus legacy SSE) for remote access.
- Auto-registered tools — a tool appears in
tools/listonly when its engine is enabled, so the surface adapts to your configuration. - Web admin UI — browse, test and hot-reload datasources without restarting the server.
Requirements
Quick Start
1. Clone and build
git clone https://github.com/11122604/light-database-mcp-server.git
cd light-database-mcp-server
./mvnw clean package -DskipTests
Output: target/turnright-database-mcp-server-0.0.1-SNAPSHOT.jar
2. Configure a datasource
cp .env.example mcp-config.env
Configuration uses the multi-datasource format only — one <DB>_ENABLED switch plus an indexed <DB>_DATASOURCES_N_<FIELD> array. The legacy single-datasource keys (DATABASE_URL, MONGODB_URI, …) have been removed.
MYSQL_ENABLED=true
MYSQL_DATASOURCES_0_NAME=default
MYSQL_DATASOURCES_0_URL=jdbc:mysql://localhost:3306/mydb
MYSQL_DATASOURCES_0_USERNAME=root
MYSQL_DATASOURCES_0_PASSWORD=secret
MYSQL_DATASOURCES_0_DESCRIPTION=Primary MySQL
MYSQL_DATASOURCES_0_READONLY=true
mcp-config.envstores credentials and is listed in.gitignore— never commit it. Every datasource needs an explicitNAME; name itdefaultwhen you only configure one.
The full field list per engine, OS-environment-variable form, and multi-datasource examples are in USAGE.md.
3. Run
./start.sh # transport and port follow mcp-config.env
./start.sh http # force HTTP
./start.sh stdio # force stdio
./start.sh 9001 # override port only
./start.sh http 9000 ./my.env # explicit mode, port and config file
On Windows use start.bat [http|stdio] [port] with the same argument rules.
The script looks for the JAR in target/ first, then falls back to a deployment JAR placed next to it.
Deployment layout — when you ship the jar instead of running from source, keep the jar, the config file and both launch scripts in the same directory:
deploy/
├── turnright-database-mcp-server-0.0.1-SNAPSHOT.jar # build output
├── mcp-config.env # datasource + transport config
├── start.sh # Linux / macOS
└── start.bat # Windows
The application resolves mcp-config.env against the current working directory (user.dir), and each script switches to its own directory before launching Java. Split them across directories and the config is silently ignored — the server starts with no datasources and list_datasources only returns a hint.
4. Connect your MCP client
stdio — the client launches the process:
{
"mcpServers": {
"turnright-database": {
"command": "java",
"args": ["-jar", "path/to/turnright-database-mcp-server-0.0.1-SNAPSHOT.jar"]
}
}
}
HTTP — connect to the Streamable HTTP endpoint:
{
"mcpServers": {
"turnright-database": {
"url": "http://localhost:9000/mcp"
}
}
}
The port follows
MCP_PORTinmcp-config.env(defaults to 8080; the bundled sample uses 9000). Legacy SSE clients can use/mcp/sseinstead.
Keep credentials in
mcp-config.envor in fully-qualified environment variables such asDATABASE_MYSQL_DATASOURCES_0_URL. Do not pass the removed single-datasource variables through your MCP client'senvblock.
Transports
HTTP endpoints:
Resolution order (highest first):
-p/--port command-line argument
> System property (-Dmcp.transport / -Dmcp.port)
> OS environment variables (MCP_TRANSPORT / MCP_PORT)
> mcp-config.env file
> defaults (stdio / 8080)
start.shandstart.batexport the keys frommcp-config.envas environment variables, overwriting any same-named variable already exported in your shell. With the launch scripts the config file therefore wins over a pre-setexport; use an explicit command-line argument to override temporarily.
Supported Databases
Available Tools
48 tools in total, including the common list_datasources. Tools are conditionally registered by Spring: when an engine is disabled (<DB>_ENABLED=false), its tools do not appear in tools/list.
Exception: the six Oracle tools are always registered and return a "not configured" error when Oracle is disabled. This is a known deviation from the rule above.
- Common —
list_datasources - MySQL —
mysql_query,mysql_execute,mysql_table_schema,mysql_list_tables,mysql_database_info - SQL Server —
sqlserver_query,sqlserver_execute,sqlserver_table_schema,sqlserver_list_tables,sqlserver_database_info,sqlserver_stored_procedure - MongoDB —
mongo_find,mongo_insert,mongo_update,mongo_delete,mongo_aggregate,mongo_list_collections,mongo_database_info - Elasticsearch —
es_search,es_get_document,es_index_document,es_update_document,es_delete_document,es_list_indices,es_index_info,es_create_index,es_cluster_info - Oracle —
oracle_query,oracle_execute,oracle_table_schema,oracle_list_tables,oracle_database_info,oracle_stored_procedure - Redis —
redis_get,redis_set,redis_delete,redis_keys,redis_scan,redis_ttl,redis_type,redis_incr,redis_decr,redis_hash_get,redis_hash_all,redis_list_range,redis_set_members,redis_info
Every tool accepts an optional datasource argument. Full parameter lists, required fields and call examples: USAGE.md (Chinese).
Multi-Datasource Usage
Pass datasource to target a specific instance; omit it to use the engine's default (set by <DB>_DEFAULT_DATASOURCE, otherwise the first configured datasource).
{
"name": "mysql_query",
"arguments": {
"datasource": "analytics",
"sql": "SELECT * FROM reports LIMIT 10"
}
}
Admin UI
Available in HTTP mode at http://localhost:<MCP_PORT>/admin.
- Browse and test — list datasources per engine and run a live connection test with latency feedback.
- Edit — create, update or delete datasources; changes to enabled engines take effect immediately without a restart.
- Write protection — modifications require an admin token. Set a non-empty
MCP_ADMIN_TOKEN(environment variable ormcp-config.env); without it the page is read-only and can only test connections.
⚠️ Saving rewrites the entire
mcp-config.env. All comments are lost, and fields the UI does not expose —MAX_POOL_SIZE,MIN_IDLE,IDLE_TIMEOUT,CONNECTION_TIMEOUT, RedisTIMEOUT/MAX_TOTAL, and similar — are not written back. Back up the file first if you rely on those hand-written values, or use the UI only for temporary changes.
Changes to a disabled engine (
<DB>_ENABLED=false) are saved to the file but require enabling the engine and restarting the server.
REST API (used by the UI; write calls require the X-Admin-Token header):
Documentation
The reference documentation below is currently written in Chinese.
- README.zh-CN.md — Chinese README
- USAGE.md — usage guide: configuration options, all tool parameters, examples
- docs/RUNBOOK.md — operations manual: deployment, endpoints, monitoring, troubleshooting
- docs/CONTRIBUTING.md — contributing guide: dev environment, tests, project layout
- docs/oracle-setup.md — installing the Oracle JDBC driver
- .env.example — configuration template (copy to
mcp-config.env)
Building and Testing
./mvnw clean package # full build with tests
./mvnw clean package -DskipTests # skip tests
./mvnw test # tests + JaCoCo coverage report
JaCoCo enforces a minimum of 80% instruction coverage; the build fails below the threshold. The report is written to target/site/jacoco/index.html.
Contributing
Contributions are welcome. See docs/CONTRIBUTING.md for the development environment, build commands, test setup, project layout, and how to add a new tool.
Commit messages follow Conventional Commits (feat:, fix:, docs:, …).
Security
- Keep
READONLY=trueon production datasources; grant database users the minimum required privileges. - Never commit
mcp-config.env— it is git-ignored by default, and only.env.examplebelongs in the repository. - Set a strong
MCP_ADMIN_TOKENbefore exposing the admin UI beyond localhost.
License
Licensed under the Apache License 2.0.