# 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

```text
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

| Database | Status |
|----------|--------|
| SQLite | ✅ Supported |
| MySQL | ✅ Supported |
| PostgreSQL | ✅ Supported |

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

## 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

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

---

## 2. Create a Virtual Environment

```bash
python -m venv .venv
```

Activate it.

Windows

```bash
.venv\Scripts\activate
```

Linux / macOS

```bash
source .venv/bin/activate
```

---

## 3. Install Dependencies

```bash
pip install -r requirements.txt
```

---

## 4. Configure the Database

Choose one configuration from the `configs/` directory.

Example:

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

---

## 5. Start the MCP Server

```bash
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.