Multi-Database MCP Server

English | Türkçe

A read-only Model Context Protocol (MCP) server built with TypeScript and TypeORM, providing a standardized way for AI applications to interact with MySQL and PostgreSQL databases.

The server enables AI clients to discover database schemas and execute validated SQL queries through two MCP tools.

Features

• Multi-database support: MySQL and PostgreSQL.
• Dynamic schema discovery: Retrieve table and column information without hardcoding database schemas.
• Read-only querying: Execute validated SELECT statements.
• SQL validation: Restrict modification commands, dangerous operations, and multiple statements.
• Result limits: Automatically limit query results to a maximum of 100 rows.
• Database-level protection: Dedicated read-only users for the included Docker databases.
• Docker support: Run both databases and the MCP server without installing database servers locally.

MCP Tools

The query tool returns:

• rows: Query results.
• rowCount: Number of returned rows.
• executionTimeMs: Query execution time in milliseconds.

The server connects to one configured database per instance.

Natural-language processing is handled by the connected AI application, not by the MCP server itself.

Architecture

User
  |
AI Application / LLM
  |
MCP Server
  |-- get_tables
  |-- query
  |     |
  |   SQL Validator
  |
Database Adapter
  |
MySQL / PostgreSQL

The project uses TypeORM for database connection and query management, with separate adapters for MySQL and PostgreSQL.

Requirements

• Docker Desktop or Docker Engine with Compose
• Node.js 22+ and npm for local tests and MCP Inspector

Local installation of MySQL or PostgreSQL is not required when using Docker.

Quick Start

The following commands are intended for Windows PowerShell. Run them from the repository root.

1. Configure the environment

Copy the example configuration:

Copy-Item .env.docker.example .env.docker

Open .env.docker and replace the four example passwords with your own local test passwords. Use letters, numbers, and underscores for simplest database URL compatibility. Never commit this private file.

2. Start the databases

docker compose --env-file .env.docker up -d --wait

Check their status:

docker compose --env-file .env.docker ps

Both MySQL and PostgreSQL should report a healthy status. Host ports default to 127.0.0.1:3307 (MySQL) and 127.0.0.1:5433 (PostgreSQL); adjust the optional ports in .env.docker if already occupied. The MCP containers use Docker-internal ports.

3. Build the MCP Docker image

docker compose --env-file .env.docker --profile mcp build mcp-postgres

Both MCP services use the same application image.

4. Connect using MCP Inspector

For PostgreSQL:

npx.cmd -y @modelcontextprotocol/inspector docker compose -f .\compose.yaml --env-file .\.env.docker --profile mcp run --rm -T mcp-postgres

Open the local Inspector URL displayed in your terminal.

Select List Tools to discover get_tables and query.

Run get_tables, then test query using:

SELECT COUNT(*) AS total_customers
FROM customers;

Expected PostgreSQL result: 91 customers.

To test MySQL, close the current Inspector session and run:

npx.cmd -y @modelcontextprotocol/inspector docker compose -f .\compose.yaml --env-file .\.env.docker --profile mcp run --rm -T mcp-mysql

Expected MySQL result for the same COUNT query: 29 customers.

For additional setup instructions, see the Reviewer Quick Start.

Included Sample Databases

Two Northwind sample database variants are provided for testing:

These datasets use different schemas and sample records. Queries written for one database may require adjustments for the other.

See Northwind Datasets for additional information.

Running Tests

Install project dependencies:

npm.cmd ci

Run the automated checks:

npm.cmd test
npm.cmd run build

npm.cmd test runs TypeScript, SQL security, and offline fixture-integrity checks; npm.cmd run build compiles the project. For macOS/Linux, use npm and npx in place of the .cmd executables and adjust the Windows-style paths.

Live database integration tests are also available. They require a separately configured read-only database connection.

Using Your Own Database

The MCP server is not limited to the included Northwind samples.

To connect to an existing MySQL or PostgreSQL database, copy .env.example to .env and configure:

• DB_TYPE: mysql or postgres
• DB_URL: Connection URL for an authorized read-only database user

The server discovers the connected database’s schema dynamically. Each process uses one configured database connection. The MCP server does not itself include an LLM or convert natural language into SQL.

Use appropriate database permissions and review the security configuration before connecting external data sources.

Connecting an AI Application

The MCP server can be used with compatible MCP clients, including MCP Inspector and AnythingLLM.

A sample AnythingLLM configuration is available in:

AnythingLLM configuration example

Update the local file paths to match your installation. The MCP services use local stdio rather than a hosted HTTP endpoint.

Example natural-language questions are available in Demo Queries.

Stopping the Environment

To stop the Docker services while preserving database data:

docker compose --env-file .env.docker down

Database data is stored in Docker volumes and remains available when the services are restarted. Initialization SQL runs only when a database volume is new/empty: changing a seed file does not replace existing stored data. Avoid down -v unless you intend to erase the demo databases.

Security

This project is designed as a read-only proof of concept.

It includes SQL validation, result limits, and dedicated database reader accounts. However, these controls do not replace production-grade authentication, authorization, query resource limits, monitoring, or a comprehensive security review.

Do not expose sensitive production databases through this demonstration setup. The 100-row output cap does not limit query cost or execution time.

See Security Notes.

License

The original application code and project documentation are released under the MIT License.

The included Northwind sample datasets retain their respective third-party licenses and attribution notices, available in docs/third_party/.