Generic SQL MCP Server

A configurable, database-agnostic Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to safely interact with SQL databases.

Overview

This project is a Proof of Concept (POC) that demonstrates how a Model Context Protocol (MCP) server can securely expose SQL database capabilities to AI assistants while maintaining a clean and configurable architecture.

Rather than connecting directly to a production database, this project uses a local demonstration database to validate the overall architecture. The design allows the same MCP server to connect to different SQL databases simply by changing configuration files, without modifying application code.

The project serves as a foundation for future integration with enterprise databases such as ERP systems.

Objectives

The primary objectives of this project are:

• Demonstrate how an MCP server communicates with SQL databases.

• Support multiple SQL database engines through configuration.

• Keep the implementation database-agnostic.

• Expose generic database capabilities to LLMs.

• Allow only safe, read-only SQL operations.

• Build a modular and extensible architecture.

Features

• Configurable database connections

• SQLite, MySQL and PostgreSQL support

• Generic SQL database tools

• Read-only SQL execution

• SQL validation layer

• Modular architecture

• Configuration-driven design

• Logging and error handling

• MCP-compliant implementation

Project Architecture

                 User

                   │

                   ▼

            MCP Client
      (Claude Desktop, etc.)

                   │

                   ▼

              MCP Server

                   │

             MCP Tools

                   │

          Database Service

                   │

         Database Adapter

                   │

             SQLAlchemy

                   │

              SQL Database

Project Structure

sql-mcp-server/

├── CLAUDE.md
├── README.md
├── requirements.md
├── architecture.md
├── tasks.md
│
├── app/
│   ├── server.py
│   ├── config.py
│   ├── database/
│   ├── tools/
│   ├── security/
│   └── utils/
│
├── configs/
│   ├── sqlite.yaml
│   ├── mysql.yaml
│   └── postgres.yaml
│
├── demo_db/
│   ├── schema.sql
│   ├── seed.sql
│   └── school.db
│
├── tests/
│
├── requirements.txt
│
└── .env.example

Supported Databases

SQLite is used as the primary demonstration database.

Supported MCP Capabilities

The MCP server provides generic database functionality rather than business-specific operations.

Examples include:

• List available tables

• Inspect table schemas

• Execute read-only SQL queries

• Retrieve database metadata

This allows the server to work with virtually any SQL database.

Security

The server operates in read-only mode.

Allowed SQL:

• SELECT

Blocked SQL:

• INSERT

• UPDATE

• DELETE

• DROP

• ALTER

• CREATE

• TRUNCATE

Every SQL statement is validated before execution.

Technology Stack

Related MCP server: sqldb-mcp-server

Language

• Python 3.12+

Core Libraries

• Official Python MCP SDK

• SQLAlchemy

• Pydantic

• PyYAML

• python-dotenv

Database Drivers

• SQLite

• PyMySQL

• psycopg2-binary

Getting Started

1. Clone the Repository

git clone <repository-url>
cd sql-mcp-server

2. Create a Virtual Environment

python -m venv .venv

Activate it.

Windows

.venv\Scripts\activate

Linux / macOS

source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure the Database

Choose one configuration from the configs/ directory.

Example:

database:
  type: sqlite
  database: demo_db/school.db

5. Start the MCP Server

python app/server.py

6. Connect an MCP Client

Connect the server using any MCP-compatible client such as:

• Claude Desktop

• Claude Code

• MCP Inspector

• Other MCP-compatible clients

Demonstration

Example interactions:

List all tables.

Describe the students table.

Show all records from teachers.

Find students older than 15.

Show the schema of attendance.

Future Improvements

Possible future enhancements include:

• Authentication

• Role-based authorization

• Query auditing

• Connection pooling

• Dynamic tool generation

• Enterprise ERP integration

• Production deployment

• Multi-database connections

• Advanced SQL validation

Documentation

Additional project documentation:

• CLAUDE.md — Instructions and development guidelines for Claude Code

• requirements.md — Functional requirements

• architecture.md — Technical architecture

• tasks.md — Development roadmap

Project Status

Current Status

🚧 Proof of Concept (POC)

The project is under active development and is intended to validate the feasibility of using MCP as a secure interface between LLMs and SQL databases.

License

This project is intended for internal evaluation and demonstration purposes.