MSSQL MCP Server

Model Context Protocol (MCP) Server để tương tác với cơ sở dữ liệu Microsoft SQL Server. Server này cho phép các AI agent tự động quét toàn bộ danh sách database, đọc thông tin schema và thực thi các câu lệnh truy vấn (read-only) một cách an toàn.

Tính năng

🗄️ Quản lý Đa Cơ Sở Dữ Liệu (Multi-Database Auto-Scan)

• mssql_list_databases: Tự động kết nối đến server và quét danh sách toàn bộ các cơ sở dữ liệu đang có (trạng thái ONLINE).
• Các công cụ thao tác đều hỗ trợ tham số database_name để AI có thể tự do chỉ định database cần truy vấn mà không cần anh cấu hình từng cái một.

🔍 Thực thi truy vấn (Query Execution)

• mssql_execute_query: Chạy các câu lệnh SQL trên một database chỉ định.
• An toàn là trên hết (Safety First): Chỉ cho phép các thao tác chỉ đọc (SELECT, WITH, EXEC, SHOW).
• Danh sách từ khóa cấm (Keyword Blacklist): Tự động chặn bất kỳ câu truy vấn nào chứa các từ khóa phá hoại như DROP, DELETE, UPDATE, INSERT, ALTER, hoặc TRUNCATE.

📥 Cách truyền tham số cho MCP tools

Các tham số được truyền trực tiếp theo tên field; không bọc trong object params.

{
  "database_name": "db_saas_culture",
  "query": "SELECT TOP 10 * FROM dbo.users",
  "limit": 100
}

Ví dụ các tool khám phá schema:

{
  "database_name": "db_saas_culture",
  "schema_name": "dbo"
}

{
  "database_name": "db_saas_culture",
  "schema_name": "dbo",
  "table_name": "users"
}

schema_name mặc định là dbo; limit mặc định là 100 và giới hạn từ 1 đến 1000.

📊 Khám phá Schema (Schema Exploration)

• mssql_list_tables: Liệt kê tất cả các bảng trong một schema cụ thể (mặc định là dbo).
• mssql_describe_table: Lấy metadata chi tiết cho các cột của một bảng cụ thể (kiểu dữ liệu, cho phép null, độ dài tối đa).

Cài đặt

Yêu cầu hệ thống (Prerequisites)

• Python 3.12+
• uv (khuyên dùng) hoặc pip
• Không cần ODBC Driver: server dùng pymssql (bundle sẵn FreeTDS), chạy được trên Alpine/Debian/Windows mà không cần cài unixodbc hay msodbcsql17.

Thiết lập (Setup)

# Di chuyển vào thư mục của server
cd servers/mssql

# Cài đặt các thư viện phụ thuộc bằng uv
uv sync

Cấu hình

Server này đọc cấu hình từ các biến môi trường (environment variables). Anh KHÔNG CẦN chỉ định database cụ thể, chỉ cần cấp thông tin máy chủ để server tự quét:

{
  "mcpServers": {
    "mssql-mcp-vn": {
      "command": "uvx",
      "args": [
        "mssql-mcp-vn"
      ],
      "env": {
        "MSSQL_SERVER": "localhost",
        "MSSQL_USER": "sa",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_PORT": "1433",
      }
    }
  }
}

Các trường cấu hình (Configuration Fields)

• MSSQL_SERVER (bắt buộc): Hostname hoặc địa chỉ IP của Server.
• MSSQL_USER (bắt buộc): Tên đăng nhập (username) SQL Server.
• MSSQL_PASSWORD (bắt buộc): Mật khẩu đăng nhập SQL Server.
• MSSQL_PORT (tùy chọn): Cổng kết nối (mặc định là 1433).
• MSSQL_CHARSET (tùy chọn): Charset kết nối (mặc định là UTF-8, hỗ trợ tiếng Việt).
• MSSQL_TDS_VERSION (tùy chọn): Giao thức TDS dùng cho pymssql (mặc định là 7.4).

Chạy Server (Run Server)

Chạy như một MCP Server (Stdio)

uv run src/mssql_mcp_server.py

Cấu hình thành một gói Package để chạy qua UVX (Optional)

Nếu anh muốn đẩy lên mạng và chạy trực tiếp bằng uvx mssql-mcp-vn (hoặc kéo từ Github):

• Trong pyproject.toml đã khai báo [project.scripts].
• Lệnh sẽ tự động gọi hàm main() trong src/mssql_mcp_server.py.
• Anh có thể đẩy source code lên Github và chạy bằng: uvx git+https://github.com/username/mssql-mcp-vn.git

Xử lý lỗi (Error Handling)

Tất cả các công cụ đều trả về chuỗi định dạng JSON hoặc thông báo lỗi rõ ràng:

• Lỗi xác thực sẽ trả về lỗi kết nối (connection errors).
• Các câu lệnh phá hoại sẽ trả về một thông báo lỗi rõ ràng "Error: Detected potentially destructive keywords in query."
• Phản hồi bình thường sẽ bao gồm số lượng dòng, tiêu đề cột và mảng dữ liệu được định dạng phù hợp để LLM có thể đọc hiểu.

Changelog

0.1.7 - 2026-08-18

Improved

• Flatten public MCP tool arguments for mssql_execute_query, mssql_list_tables, and mssql_describe_table so Form Mode and AI clients can pass fields directly without a params wrapper.
• Add clearer parameter descriptions, examples, schema regression tests, and documented MCP payloads.

0.1.6 - 2026-08-11

Changed

• Thay pyodbc + aioodbc bằng pymssql (bundle FreeTDS) để chạy không cần cài unixodbc/msodbcsql17 trên máy host. Fix lỗi ImportError: libodbc.so.2 khi chạy trong container.
• Đổi biến cấu hình: bỏ MSSQL_DRIVER, thêm MSSQL_CHARSET (mặc định UTF-8) và MSSQL_TDS_VERSION (mặc định 7.4).
• Các tool chuyển từ async sang sync (pymssql là driver đồng bộ).

0.1.5 - 2026-08-10

Improved

• Tự detect ODBC driver tốt nhất có trên máy (ưu tiên ODBC Driver 18, sau đó 17/13) thay vì hardcode driver 17, giúp chạy được trên Ubuntu mới chỉ có driver 18.

Note

• Package chỉ cài qua pip/uv phần Python; ODBC driver phải được cài riêng trên máy host (không cài được qua pip).

0.1.4 - 2026-08-10

Fixed

• Khóa mcp>=1.2.0,<2 để tránh uvx resolve nhầm lên mcp 2.0.0, bản này đã bỏ mcp.server.fastmcp khiến server crash với ModuleNotFoundError: No module named 'mcp.server.fastmcp'.

0.1.3 - 2026-07-05

Fixed

• Publish script giờ tự chuyển vào đúng thư mục uvx/mssql trước khi chạy uv build, nên gọi bằng absolute path từ root repo không còn sinh artifact lỗi unknown-0.0.0.
• Build output giờ ra đúng package mssql_mcp_vn-0.1.3 thay vì dùng nhầm root pyproject.toml.
• Metadata package dùng license = "MIT" để tránh warning deprecated từ setuptools.

Improved

• Tên package, command và hướng dẫn chạy được chuẩn hóa về mssql-mcp-vn.
• Publish script cleanup dist, build, và src/*.egg-info trước khi build để tránh upload nhầm artifact cũ.

0.1.2 - 2026-07-05

New

• Package MSSQL MCP ban đầu với các tool mssql_list_databases, mssql_execute_query, mssql_list_tables, và mssql_describe_table.
• Hỗ trợ quét database online, khám phá schema, và chạy truy vấn SQL có guard chống thao tác phá hoại.