Content
# MCP SQL Server
MCP (Model Context Protocol) for managing SQL Server databases. Exposes query, analysis, modification, and connection configuration tools via FastMCP.
---
## Requirements
- Python 3.10+
- ODBC Driver for SQL Server
- opencode (or any MCP client)
### ODBC Driver
**Windows**
```
Download and install: https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server
```
**Linux (Ubuntu/Debian)**
```bash
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc
sudo add-apt-repository "$(curl -fsSL https://packages.microsoft.com/config/ubuntu/$(lsb_release -rs)/prod.list)"
sudo apt-get update
sudo apt-get install -y mssql-tools18 unixodbc-dev
```
**Linux (RHEL/Fedora)**
```bash
sudo curl -o /etc/yum.repos.d/mssql-release.repo https://packages.microsoft.com/config/rhel/8/prod.repo
sudo yum install -y mssql-tools18 unixodbc-devel
```
---
## Installation
**1. Clone the repository**
```bash
git clone <repo-url>
cd MCP_SQLSERVER
```
**2. Create virtual environment**
```bash
# Windows
python -m venv .venv
.venv\Scripts\activate
# Linux
python3 -m venv .venv
source .venv/bin/activate
```
**3. Install dependencies**
```bash
pip install -r requirements.txt
```
---
## MCP configuration in opencode
Add this to your opencode config file (`opencode.json` or `~/.config/opencode/opencode.json`):
**Linux**
```json
{
"mcp": {
"sqlserver": {
"type": "local",
"enabled": true,
"command": [
"/full/path/to/MCP_SQLSERVER/.venv/bin/python",
"/full/path/to/MCP_SQLSERVER/Server.py"
]
}
}
}
```
**Windows**
```json
{
"mcp": {
"sqlserver": {
"type": "local",
"enabled": true,
"command": [
"C:\\full\\path\\to\\MCP_SQLSERVER\\.venv\\Scripts\\python.exe",
"C:\\full\\path\\to\\MCP_SQLSERVER\\Server.py"
]
}
}
}
```
---
## Getting started (configuring the connection)
When the MCP starts for the first time, the connection is empty. The assistant will guide you to configure it using these tools:
| Tool | Parameters | Description |
|---|---|---|
| `configure_connection` | server, auth_type, database, port, driver, username, password, trust_server_certificate, sql_repository | Sets all parameters at once |
| `set_config` | server, port, database, driver, auth_type, username, password, trust_server_certificate, sql_repository | Updates only the given fields (the rest are preserved) |
| `get_config` | — | Shows the current config (password is hidden) |
| `test_connection` | database (optional) | Tests connectivity with the current settings |
**Typical flow:**
```
1. configure_connection(
server="MY-SERVER",
port="1433",
auth_type="sqlserver",
username="my_user",
password="my_password",
database="MyDB"
)
2. test_connection()
3. list_databases()
4. list_tables("MyDB")
5. describe_table("MyDB", "MyTable")
```
### Authentication types
- **windows**: Uses `Trusted_Connection=yes`. No username or password required (domain session).
- **sqlserver**: Uses `UID` and `PWD`. Requires username and password.
> The configuration is persisted in `config.json`. You can change server or database at any time by calling `configure_connection` or `set_config` again.
---
## MCP Tools
### Configuration
| Tool | Parameters | Description |
|---|---|---|
| `get_config` | — | Shows current config (password hidden) |
| `set_config` | server, port, database, driver, auth_type, username, password, trust_server_certificate, sql_repository | Updates specific fields in `config.json` |
| `configure_connection` | server, auth_type, database, port, driver, username, password, trust_server_certificate, sql_repository | Sets all connection parameters at once |
| `test_connection` | database (optional) | Tests the connection with the current config |
### Object exploration
| Tool | Parameters | Description |
|---|---|---|
| `ping` | — | Checks SQL Server connectivity |
| `list_databases` | — | Lists all active databases |
| `list_tables` | database | Lists tables in a database |
| `describe_table` | database, table | Columns, types, nulls, defaults |
| `list_procedures` | database | Lists stored procedures |
| `describe_procedure` | database, procedure | Source code and parameters of the SP |
| `list_functions` | database | Lists functions |
| `describe_function` | database, function | Source code and parameters of the function |
| `search_tables` | database, text | Searches tables by partial name (LIKE) |
| `search_columns` | database, text | Searches columns by name across all tables |
| `search_procedures` | database, text | Searches SP by partial name |
| `search_text` | database, text | Searches text in SP/function definitions |
| `list_foreign_keys` | database | Lists all FK in the database |
| `find_relationships` | database, table | Incoming and outgoing relationships of a table |
### Data manipulation
| Tool | Parameters | Description |
|---|---|---|
| `execute_query` | database, query | SELECT or CTE (read-only with validation) |
| `execute_dml` | database, query, confirmed | INSERT/UPDATE/DELETE (requires confirmed=True) |
| `execute_ddl` | database, sql_text, description | CREATE/ALTER with automatic migration |
---
## Change tracking (Logs and migrations)
Every time you run `execute_ddl` (CREATE/ALTER), the system automatically saves the full history in `sql_repository`. You never lose track of what was modified.
### What is saved?
```
sql_repository/
└── MyDB/
├── Procedures/
│ └── MyProcedure/
│ └── Current.sql ← current definition with history
├── Functions/
├── Views/
├── Tables/
├── Migrations/
│ └── Procedures/
│ └── 20260724_001_MyProcedure.sql ← each change is a file
└── Logs/
└── Changes.jsonl ← full audit log in JSONL
```
- **Current.sql**: Contains the current object definition plus a `HISTORY` block with all previous versions, date, author, and summary of each change.
- **Migrations/**: Each DDL generates a versioned SQL file (`YYYYMMDD_NNN_Name.sql`) with the exact change. You can review or revert manually.
- **Logs/Changes.jsonl**: Audit log in JSONL format (one line per change), easy to process with scripts or search with grep.
### Example entry in Changes.jsonl
```json
{"date": "2026-07-24T20:04:33", "database": "MyDB", "objectType": "PROCEDURE", "object": "MyProcedure", "operation": "CREATE", "description": "Create test procedure", "migration": "20260724_001_MyProcedure.sql"}
```
### Why is this important?
- You can revert to a previous version of any object at any time.
- You know exactly what changed, when, and who did it.
- The full `sql_repository` can be versioned in Git for end-to-end traceability.
