# SQL MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes a SQLite database to any MCP-compatible client — including Claude Desktop, Claude Code, and custom agents.

## What it does

Gives an AI assistant structured, read-safe access to a relational database through five tools. The assistant can explore the schema, run SELECT queries, and retrieve sample data — without any risk of writes or destructive operations.

---

## Schema

Five tables with realistic foreign-key relationships:

```
users ──< orders ──< order_items >── products
  │
  └──< support_tickets
```

| Table | Description |
|---|---|
| `users` | 20 registered customers |
| `products` | 30-item product catalog with categories and stock levels |
| `orders` | 30 purchase records linked to users |
| `order_items` | ~55 line items linking orders to specific products |
| `support_tickets` | 35 support requests with status and priority |

---

## MCP Tools

| Tool | Description |
|---|---|
| `list_tables` | Returns all table names in the database |
| `describe_table(table_name)` | Returns column metadata — name, type, nullability, defaults, PK flag |
| `run_query(sql)` | Executes a SELECT query and returns rows as JSON. Non-SELECT statements are rejected. |
| `get_sample_rows(table_name, limit=5)` | Returns up to 100 sample rows from any table |
| `get_schema_summary` | Returns a plain-English summary of all 5 tables — columns, types, and FK relationships — in one call |

### Security

- `run_query` checks the first SQL token and rejects anything that isn't `SELECT`
- Multi-statement queries (containing `;`) are blocked
- Table name parameters are validated against `[A-Za-z_][A-Za-z0-9_]*` before interpolation

---

## Setup

**1. Install dependencies**

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

**2. Seed the database**

```bash
python seed.py
```

This creates `test.db` in the same directory with all 5 tables populated.

**3. Run the server**

```bash
python server.py
```

The server communicates over stdio using the MCP protocol.

---

## Claude Desktop Integration

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sql-mcp": {
      "command": "python3",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}
```

Config file locations:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Restart Claude Desktop after saving.

---

## Verify Tools (without Claude Desktop)

`test_tools.py` connects to the server via stdio and exercises all 5 tools:

```bash
python test_tools.py
```

Expected output confirms:
- All 5 tools are registered
- Each tool returns correct results
- `run_query` rejects non-SELECT statements

---

## Project Structure

```
.
├── server.py         # MCP server — 5 tools
├── seed.py           # Creates and populates test.db
├── test_tools.py     # Stdio client verification script
├── requirements.txt  # mcp, aiosqlite
└── .gitignore
```

---

## Requirements

- Python 3.10+
- `mcp` — MCP server framework
- `aiosqlite` — async SQLite driver