MSSQL MCP Server

MCP server Python cho Microsoft SQL Server, dùng pymssql/FreeTDS nên không cần ODBC driver. Bản 0.2.0 hỗ trợ truy vấn chỉ đọc, full backup .bak chạy nền và so sánh relational schema giữa hai database trên cùng instance.

Tools

• mssql_list_databases(): liệt kê database ONLINE mà principal nhìn thấy.
• mssql_execute_query(database_name, query, limit=100): chỉ nhận SELECT hoặc CTE chỉ đọc; chặn EXEC, SELECT INTO, DDL/DML, BACKUP, RESTORE và DBCC.
• mssql_list_tables(database_name, schema_name="dbo").
• mssql_describe_table(database_name, table_name, schema_name="dbo").
• mssql_start_backup(database_name): full COPY_ONLY, CHECKSUM, tự động bỏ COMPRESSION trên SQL Server Express, một job tại một thời điểm. Tool trả ngay backup_id sau preflight.
• mssql_get_backup_status(backup_id): trả queued | running | succeeded | failed, percent_complete, paths, kích thước file, verify và lỗi có hướng xử lý.
• mssql_compare_schemas(source_database, target_database, schema_name=null, offset=0, limit=100): so sánh tables, columns, PK, FK, unique/check constraints và indexes; limit từ 1 đến 500.

Mọi argument public đều truyền phẳng, không bọc trong params.

Cài và chạy

cd uvx/mssql
uv sync --extra dev
uv run mssql-mcp-vn

Stdio là mặc định. Streamable HTTP dùng tên SDK streamable-http; alias streamable_http vẫn được chấp nhận và bind loopback theo mặc định:

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8003 uv run mssql-mcp-vn

Cấu hình

{
  "mcpServers": {
    "mssql-mcp-vn": {
      "command": "uvx",
      "args": ["mssql-mcp-vn==0.2.0"],
      "env": {
        "MSSQL_SERVER": "sql.internal.example",
        "MSSQL_USER": "mssql_mcp",
        "MSSQL_PASSWORD": "<secret-from-secret-store>",
        "MSSQL_PORT": "1433",
        "MSSQL_BACKUP_SQL_ROOT": "\\\\fileserver\\mssql-backups",
        "MSSQL_BACKUP_LOCAL_ROOT": "/srv/mssql-backups"
      }
    }
  }
}

MSSQL_BACKUP_SQL_ROOT là đường dẫn SQL Server nhìn thấy. MSSQL_BACKUP_LOCAL_ROOT là cùng storage được mount trên máy Linux chạy MCP. MCP không tải file 10 GB qua TDS.

Principal tối thiểu

Không chạy MCP bằng sa. Tạo login riêng, rồi cấp quyền trên từng database được phép đọc/backup:

CREATE LOGIN [mssql_mcp] WITH PASSWORD = '<generate-and-store-separately>';
GO
USE [application_db];
CREATE USER [mssql_mcp] FOR LOGIN [mssql_mcp];
ALTER ROLE [db_datareader] ADD MEMBER [mssql_mcp];
ALTER ROLE [db_backupoperator] ADD MEMBER [mssql_mcp];
GRANT VIEW DEFINITION TO [mssql_mcp];
GO

RESTORE VERIFYONLY cần quyền CREATE DATABASE để đọc thông tin backup. Cấp cho user trong master nếu tool backup phải verify:

USE [master];
CREATE USER [mssql_mcp] FOR LOGIN [mssql_mcp];
GRANT CREATE DATABASE TO [mssql_mcp];
GO

Đọc percent_complete từ sys.dm_exec_requests cần VIEW SERVER STATE (hoặc VIEW SERVER PERFORMANCE STATE trên SQL Server 2022+). Nếu không cấp, backup vẫn chạy nhưng phần trăm có thể là null; cân nhắc quyền này theo chính sách bảo mật.

Runbook shared storage

SQL Server service account phải có quyền đọc/ghi trực tiếp share; quyền của principal SQL không thay thế quyền filesystem.

Windows SQL Server -> Samba/SMB trên Linux

1. Export một thư mục, ví dụ /srv/mssql-backups, bằng Samba.
2. Cấp ACL share và filesystem cho domain/service account chạy SQL Server.
3. Đặt MSSQL_BACKUP_SQL_ROOT=\\fileserver\mssql-backups.
4. Trên máy MCP, dùng chính thư mục local hoặc mount cùng share vào /srv/mssql-backups, rồi đặt MSSQL_BACKUP_LOCAL_ROOT tương ứng.
5. Dùng service account kiểm tra tạo/xóa một file thử trước khi gọi backup.

Linux SQL Server -> NFS hoặc SMB mount

1. Mount NFS/SMB tại một path cố định trên host SQL Server, ví dụ /mnt/mssql-backups; service mssql-server phải đọc/ghi được.
2. Mount cùng export trên máy MCP tại /srv/mssql-backups.
3. Đặt MSSQL_BACKUP_SQL_ROOT=/mnt/mssql-backups và MSSQL_BACKUP_LOCAL_ROOT=/srv/mssql-backups.
4. Khai báo mount bền vững bằng cơ chế của hệ điều hành và kiểm tra mount đã sẵn sàng trước khi start MCP.

Tham khảo Microsoft: backup devices, full database backup, và RESTORE VERIFYONLY.

Vòng đời backup

Preflight yêu cầu database ONLINE, principal có BACKUP DATABASE, local root là folder tuyệt đối có quyền đọc/ghi, và dung lượng trống ít nhất 110% allocated database size. SQL ghi file duy nhất *.bak.partial; MCP chạy RESTORE VERIFYONLY ... WITH CHECKSUM, rồi atomic rename thành .bak trên local mount.

MCP tự đọc SERVERPROPERTY('EngineEdition') trên connection của job. Backup bỏ COMPRESSION khi edition là SQL Server Express để tránh lỗi 1844; COPY_ONLY, CHECKSUM và STATS = 5 luôn được giữ nguyên. Worker dùng query timeout 24 giờ (86.400 giây) để backup lớn qua SMB không kế thừa timeout DB-Lib ngắn hơn.

Registry job và khóa một-job chỉ sống trong process. Không restart MCP giữa chừng. Phiên bản này không overwrite, cancel, retention, differential hoặc log backup. Khi lỗi, chỉ file partial do job đó tạo bị xóa.

So sánh schema

Hai database bắt buộc khác nhau và nằm trên instance đã cấu hình. schema_name=null quét mọi user table schema. Kết quả được sort ổn định và phân loại only_in_source, only_in_target, different; tool không sinh migration SQL. Views, procedures, functions, triggers, users, permissions và system objects nằm ngoài phạm vi.

Phát triển

cd uvx/mssql
pytest tests -v
ruff check src tests
ruff format --check src tests
mypy src
uv build

Fixture staging và 10 evaluation cố định nằm trong evaluations/.

Changelog

0.2.2 - 2026-09-02

• Đặt query timeout backup rõ ràng là 24 giờ để tránh TDS timeout khi ghi file lớn qua SMB.
• Giữ backup SQL Server Express không dùng COMPRESSION.

0.2.0 - 2026-09-01

• Thêm full background .bak backup với preflight, DMV progress, checksum verify và atomic finalization.
• Thêm relational schema compare có filter và pagination ổn định.
• Khóa query tool về SELECT/read-only CTE và chặn EXEC/INTO cùng DDL/DML.
• Sửa transport thành streamable-http, bind mặc định 127.0.0.1.
• Thêm fixture, evaluations, schema regression và unit tests.

0.1.7 - 2026-08-18

• Public MCP tools dùng flat arguments và có schema regression tests.