Metadata-Version: 2.4
Name: mcp-tools-sql
Version: 0.1.0
Summary: An MCP server for safe, configurable SQL database access
Author: Marcus Jellinghaus
License: MIT
Project-URL: Homepage, https://github.com/MarcusJellinghaus/mcp-tools-sql
Project-URL: Bug Tracker, https://github.com/MarcusJellinghaus/mcp-tools-sql/issues
Project-URL: Documentation, https://github.com/MarcusJellinghaus/mcp-tools-sql#readme
Keywords: mcp,sql,database,llm,claude,ai,sql-server,postgresql,sqlite
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: MIT License
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.3.0
Requires-Dist: mcp[cli]>=1.3.0
Requires-Dist: structlog>=24.5.0
Requires-Dist: python-json-logger>=3.2.1
Requires-Dist: mcp-coder-utils
Requires-Dist: tabulate>=0.9.0
Requires-Dist: pydantic>=2.0
Requires-Dist: tomlkit>=0.13.0
Requires-Dist: sqlparse>=0.5
Provides-Extra: mssql
Requires-Dist: pyodbc>=5.0.0; extra == "mssql"
Provides-Extra: postgresql
Requires-Dist: psycopg[binary]>=3.1.0; extra == "postgresql"
Provides-Extra: all-backends
Requires-Dist: pyodbc>=5.0.0; extra == "all-backends"
Requires-Dist: psycopg[binary]>=3.1.0; extra == "all-backends"
Provides-Extra: dev
Requires-Dist: mcp-workspace; extra == "dev"
Requires-Dist: mcp-coder; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: tach>=0.15.0; extra == "dev"
Requires-Dist: pycycle>=0.0.8; extra == "dev"
Requires-Dist: vulture>=2.13; extra == "dev"
Requires-Dist: pydeps>=1.12.0; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Dynamic: license-file

# mcp-tools-sql

> **Status: Under active development — not yet functional.**

An MCP server for safe, configurable SQL database access. Exposes schema introspection, user-defined SELECT queries, and structured UPDATE operations as MCP tools for LLM-assisted workflows.

## Key Ideas

- **Configurable, not ad-hoc**: Every query the LLM can run is defined upfront in config. The config is the security boundary.
- **Schema discovery**: Built-in tools to explore schemas, tables, columns, and foreign key relations.
- **Structured updates**: UPDATE operations are defined as table + key + fields, not raw SQL. The server generates the SQL.
- **Split config**: Query definitions live in the project repo (safe to commit). Credentials live in the user's home directory (never committed).
- **Multi-backend**: MS SQL Server (primary), PostgreSQL, SQLite.

## Architecture

```
MCP Client (Claude Code, etc.)
    ↕ STDIO/MCP
mcp-tools-sql server
    ├── Built-in tools (schema introspection)
    ├── Configured query tools (from mcp-tools-sql.toml)
    ├── Configured update tools (from mcp-tools-sql.toml)
    └── Backend abstraction
         ├── SQLite (stdlib)
         ├── MS SQL Server (pyodbc)
         └── PostgreSQL (psycopg)
```

See [docs/architecture/architecture.md](docs/architecture/architecture.md) for details.

## Installation

```bash
pip install mcp-tools-sql              # core + SQLite
pip install mcp-tools-sql[mssql]       # + SQL Server support
pip install mcp-tools-sql[postgresql]  # + PostgreSQL support
```

## Quick Start

```bash
# Generate starter project query config (mcp-tools-sql.toml) and a
# database config skeleton at ~/.mcp-tools-sql/config.toml
mcp-tools-sql init --backend sqlite

# Edit ~/.mcp-tools-sql/config.toml and set the SQLite path, e.g.:
#     [connections.default]
#     backend = "sqlite"
#     path = "./mydb.db"

# Validate environment, configs, dependencies, and connectivity
mcp-tools-sql verify

# Start MCP server
mcp-tools-sql --config mcp-tools-sql.toml
```

See [docs/cli.md](docs/cli.md) for the full CLI reference (all flags,
example output, exit codes).

## Configuration

Two config files:

| File | Purpose | Location |
|------|---------|----------|
| `mcp-tools-sql.toml` | Query/update definitions | Project dir (committed) |
| `~/.mcp-tools-sql/config.toml` | Database connections + credentials | User home (never committed) |

The `--config` flag overrides the project query config path; the
`--database-config` flag overrides the database config path.

See the [planning document](mcp-tools-sql.md) for full details.

## License

MIT
