# MCP SQL Query — SQLite Database Operations for AI Agents

> An MCP server that gives AI agents SQLite database access: execute SQL, inspect schemas, CRUD operations, export to JSON/CSV — 13 tools, zero dependencies, pure Python stdlib.

## Features

- **13 MCP Tools**: `execute_sql`, `execute_batch`, `list_tables`, `table_schema`, `create_table`, `insert_row`, `insert_batch`, `select_rows`, `update_rows`, `delete_rows`, `export_json`, `export_csv`, `database_info`
- **Zero dependencies** — pure Python stdlib (sqlite3, json, re, os)
- **SQL injection prevention** — table name validation with regex
- **Batch transactions** — execute multiple statements atomically with rollback
- **Data export** — JSON array or CSV string output
- **In-memory or file-based** — use `:memory:` for ephemeral DBs or file paths for persistence
- **STDIO JSON-RPC mode** — drop-in for Claude Desktop, Hermes, or any MCP client

## Quick Start

```bash
python -m src.server --stdio    # STDIO mode
python -m src.server --manifest # Print manifest
```

### Use as a library

```python
from src.server import MCPSQLQueryServer
import json

server = MCPSQLQueryServer()

# Create a table
server.handle_tool_call("create_table", {
    "table_name": "users",
    "columns": [
        {"name": "id", "type": "INTEGER", "primary_key": True},
        {"name": "name", "type": "TEXT", "not_null": True},
        {"name": "email", "type": "TEXT", "unique": True}
    ]
})

# Insert rows
server.handle_tool_call("insert_row", {
    "table_name": "users",
    "data": {"name": "Alice", "email": "alice@example.com"}
})

# Query
result = server.handle_tool_call("select_rows", {
    "table_name": "users",
    "where": "name = 'Alice'"
})

# Export
server.handle_tool_call("export_csv", {"table_name": "users"})
```

## MCP Tool Reference

| Tool | Description | Required Params |
|------|-------------|-----------------|
| `execute_sql` | Raw SQL execution | `sql` |
| `execute_batch` | Transactional batch | `statements` |
| `list_tables` | List all tables | — |
| `table_schema` | Column/types/indexes | `table_name` |
| `create_table` | Create with columns | `table_name`, `columns` |
| `insert_row` | Insert one row | `table_name`, `data` |
| `insert_batch` | Insert multiple | `table_name`, `rows` |
| `select_rows` | SELECT with WHERE/LIMIT | `table_name` |
| `update_rows` | UPDATE with WHERE | `table_name`, `set_values`, `where` |
| `delete_rows` | DELETE with WHERE | `table_name`, `where` |
| `export_json` | Export as JSON | `table_name` |
| `export_csv` | Export as CSV | `table_name` |
| `database_info` | DB metadata | — |

## Tests

```bash
python -m pytest tests/ -v  # 33 tests, all passing
```

## License

MIT

## Author

AMEOBIUS — [github.com/AMEOBIUS](https://github.com/AMEOBIUS)