Enhanced MCP server for SQL Server and filesystem access with dual interface support (Web UI and Desktop Application)

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for penjay from gravatar.com penjay

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: PJ
  • Tags cross-platform , database , desktop-app , dual-interface , filesystem , interactive , mcp , native-app , precompiled-binaries , sqlserver , web-ui
  • Requires: Python >=3.11
  • Provides-Extra: desktop , dev
Classifiers
Report project as malware

Project description

MCP SQL Server Filesystem

🚀 Enhanced MCP server for SQL Server database and filesystem access with dual interface support (Web UI and Desktop Application).

Read this in other languages: English | 中文

English

✨ Features

  • 🗄️ Complete SQL Server Support - Execute all SQL commands with detailed operation tracking
  • 📁 Full Filesystem Access - Read/write files with advanced security controls
  • 🌐 SQL Results Display UI - Pure display interface for SQL query results with modern responsive design
  • 🖥️ Desktop Application - Cross-platform native desktop app for SQL results visualization
  • 🔍 Smart Environment Detection - Auto-adapts to SSH Remote, WSL, Local environments
  • 🔐 Enhanced Connection Parameters - Built-in support for TrustServerCertificate=true, Encrypt=false, MultipleActiveResultSets=true
  • ⚡ Display-Only Architecture - UI shows SQL results automatically, no user interaction required
  • 🎨 Clean Results Display - Professional table formatting for SQL query results and schema information
  • 🔄 Real-time Updates - WebSocket-based automatic display when AI assistant executes SQL queries
  • 📊 Detailed Operation Results - Shows affected records count and execution details for all SQL operations

🚀 Quick Start

📦 Zero-Installation Usage (Recommended)

# Install uv (if not already installed)
pip install uv

# Run directly - no need to clone repository or install Rust!
uvx mcp-sqlserver-filesystem@latest

🧪 Testing SQL Results Display

# Test Web UI (browser-based SQL results display)
uvx mcp-sqlserver-filesystem@latest --test-web

# Test Desktop Application (native SQL results display with auto-fallback)
uvx mcp-sqlserver-filesystem@latest --test-desktop

Note: The UI is designed for displaying SQL query results only. File operations are performed in the background and do not require UI interaction.

🖥️ Desktop Application

Features

  • Zero Rust Installation Required: Uses pre-compiled binaries with intelligent fallback
  • Cross-platform Support: Windows, macOS, Linux
  • Auto-Fallback System: Automatically switches to Web UI if desktop app unavailable
  • Modern Interface: Professional design with tabbed navigation
  • Real-time Updates: WebSocket communication with backend
  • No Dependencies: Just needs uv + ODBC Driver

How It Works

  1. First Priority: Uses pre-compiled desktop binary (if available)
  2. Smart Fallback: Automatically launches Web UI if desktop unavailable
  3. Zero Maintenance: No user installation or setup required

📋 System Requirements

All platforms:

  1. Python 3.11+
  2. ODBC Driver for SQL Server ⭐ Critical!
  3. uv (for package execution)

Windows users:

# Check Python version
python --version

# Check ODBC drivers
python -c "import pyodbc; print([d for d in pyodbc.drivers() if 'SQL Server' in d])"

# Install ODBC Driver (choose one method):
# Method 1: winget (recommended)
winget install Microsoft.ODBCDriverforSQLServer

# Method 2: Chocolatey
choco install sqlserver-odbcdriver

Download links:

🔧 Augment Code Configuration

Option 1: Complete Setup (Database + Filesystem)

{
  "mcpServers": {
    "mcp-sqlserver-filesystem": {
      "command": "uvx",
      "args": ["mcp-sqlserver-filesystem@latest"],
      "timeout": 600,
      "env": {
        "DB_SERVER": "localhost",
        "DB_DATABASE": "your_database", 
        "DB_USE_WINDOWS_AUTH": "true",
        "DB_TRUST_SERVER_CERTIFICATE": "true",
        "FS_ALLOWED_PATHS": "C:\\Users\\YourName\\Documents,D:\\Projects",
        "FS_ALLOWED_EXTENSIONS": ".txt,.md,.py,.json,.sql,.csv",
        "FS_IGNORE_FILE_LOCKS": "true"
      },
      "autoApprove": [
        "sql_query", "list_tables", "get_table_schema",
        "read_file", "write_file", "list_directory"
      ]
    }
  }
}

Option 2: SQL Server Authentication + Full Filesystem Access

{
  "mcpServers": {
    "mcp-sqlserver-filesystem": {
      "command": "uvx", 
      "args": ["mcp-sqlserver-filesystem@latest"],
      "timeout": 600,
      "env": {
        "DB_SERVER": "your-server",
        "DB_DATABASE": "your_database",
        "DB_USE_WINDOWS_AUTH": "false",
        "DB_USERNAME": "sa",
        "DB_PASSWORD": "your_password",
        "FS_ALLOWED_PATHS": "*",
        "FS_ALLOWED_EXTENSIONS": "*.*",
        "FS_IGNORE_FILE_LOCKS": "true"
      },
      "autoApprove": [
        "sql_query", "list_tables", "get_table_schema",
        "read_file", "write_file", "list_directory"
      ]
    }
  }
}

Option 3: Security-Restricted Mode (Production)

{
  "mcpServers": {
    "mcp-sqlserver-filesystem": {
      "command": "uvx",
      "args": ["mcp-sqlserver-filesystem@latest"],
      "timeout": 600,
      "env": {
        "DB_SERVER": "prod-server.company.com",
        "DB_DATABASE": "ProductionDB", 
        "DB_USE_WINDOWS_AUTH": "false",
        "DB_USERNAME": "readonly_user",
        "DB_PASSWORD": "secure_password",
        "FS_ALLOWED_PATHS": "C:\\Projects\\Safe,D:\\Data\\ReadOnly",
        "FS_ALLOWED_EXTENSIONS": ".txt,.log,.json,.csv", 
        "FS_ENABLE_WRITE": "false",
        "FS_ENABLE_DELETE": "false",
        "SEC_ENABLE_SQL_PROTECTION": "true"
      },
      "autoApprove": [
        "sql_query", "list_tables", "get_table_schema", 
        "read_file", "list_directory"
      ]
    }
  }
}

🛠️ Environment Variables

Database Configuration

Variable Default Description
DB_SERVER localhost SQL Server hostname or IP
DB_DATABASE master Database name
DB_USE_WINDOWS_AUTH true Use Windows Authentication
DB_USERNAME - SQL Server username (if not using Windows auth)
DB_PASSWORD - SQL Server password (if not using Windows auth)
DB_TRUST_SERVER_CERTIFICATE true Trust server certificate
DB_ENCRYPT false Enable connection encryption
DB_MULTIPLE_ACTIVE_RESULT_SETS true Enable MARS

Filesystem Configuration

Variable Default Description
FS_ALLOWED_PATHS [] Allowed base paths (empty or * = allow all)
FS_ALLOWED_EXTENSIONS [] Allowed file extensions (empty or *.* = allow all)
FS_ENABLE_WRITE true Enable write operations
FS_ENABLE_DELETE true Enable delete operations
FS_IGNORE_FILE_LOCKS true Ignore file locks for better compatibility
FS_MAX_FILE_SIZE 1073741824 Maximum file size (1GB)

Security Configuration

Variable Default Description
SEC_ENABLE_SQL_PROTECTION false Enable SQL injection protection
SEC_MAX_QUERY_LENGTH 100000 Maximum SQL query length
SEC_ENABLE_QUERY_LOGGING true Enable query logging

📚 Available Tools

Database Operations

  • sql_query - Execute SELECT queries with detailed results
  • list_tables - List all database tables
  • get_table_schema - Get detailed table structure information

Filesystem Operations

  • read_file - Read file contents with encoding detection
  • write_file - Write file contents with confirmation
  • list_directory - List directory contents with metadata

🎯 Usage Examples

SQL Operations with Detailed Tracking

# Execute query - shows column names, data types, and row counts
result = sql_query("SELECT TOP 10 * FROM users ORDER BY created_date DESC")

# INSERT operation - shows exactly which records were inserted  
result = sql_query("INSERT INTO users (name, email) VALUES ('John', 'john@example.com')")

# UPDATE operation - shows affected records before and after
result = sql_query("UPDATE users SET status = 'active' WHERE last_login > '2024-01-01'") 

# DELETE operation - shows exactly which records were deleted
result = sql_query("DELETE FROM users WHERE status = 'inactive'")

Filesystem Operations with Security

# Read files (supports locked files)
content = read_file("C:/Projects/config.json") 

# Write files with confirmation
write_file("C:/Projects/output.txt", "Hello World!")

# List directories with metadata
files = list_directory("C:/Projects")

🔧 Development Setup (Optional)

Only needed if you want to contribute or build from source:

# Clone repository
git clone https://github.com/ppengit/mcp-sqlserver-filesystem.git
cd mcp-sqlserver-filesystem

# Install development dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest

# Run from source
python -m mcp_sqlserver_filesystem --test-web

🚨 Troubleshooting

Common Issues

  1. "No module named 'pyodbc'"

    # Install ODBC driver first, then retry
winget install Microsoft.ODBCDriverforSQLServer

  2. Connection timeout issues

    "env": {
  "DB_CONNECTION_TIMEOUT": "60",
  "DB_COMMAND_TIMEOUT": "120"
}

  3. Desktop app not launching

    • No problem! The system automatically falls back to Web UI
    • Check browser opens at http://localhost:8765

  4. File access denied

    "env": {
  "FS_IGNORE_FILE_LOCKS": "true"
}

中文

✨ 主要功能

  • 🗄️ 完整SQL Server支持 - 执行所有SQL命令，详细跟踪操作记录
  • 📁 全面文件系统访问 - 读写文件，支持高级安全控制
  • 🌐 SQL结果显示界面 - 专门用于显示SQL查询结果的纯展示界面，现代响应式设计
  • 🖥️ 桌面应用程序 - 跨平台原生桌面应用，用于SQL结果可视化展示
  • 🔍 智能环境检测 - 自动适配SSH远程、WSL、本地环境
  • 🔐 增强连接参数 - 内置支持TrustServerCertificate=true、Encrypt=false、MultipleActiveResultSets=true
  • ⚡ 纯显示架构 - UI自动显示SQL结果，无需用户交互操作
  • 🎨 清晰结果展示 - 专业的表格格式显示SQL查询结果和表结构信息
  • 🔄 实时自动更新 - 当AI助手执行SQL查询时，通过WebSocket自动显示结果
  • 📊 详细操作结果 - 显示所有SQL操作的受影响记录数和执行详情

🚀 快速开始

📦 零安装使用方式（推荐）

# 安装uv（如果尚未安装）
pip install uv

# 直接运行 - 无需克隆仓库或安装Rust！
uvx mcp-sqlserver-filesystem@latest

🧪 测试SQL结果显示

# 测试Web UI（基于浏览器的SQL结果显示）
uvx mcp-sqlserver-filesystem@latest --test-web

# 测试桌面应用（原生SQL结果显示，自动回退）
uvx mcp-sqlserver-filesystem@latest --test-desktop

注意：UI专门用于显示SQL查询结果。文件操作在后台执行，不需要UI交互。

🖥️ 桌面应用

功能特性

  • 无需安装Rust：使用预编译二进制文件，智能回退机制
  • 跨平台支持：Windows、macOS、Linux
  • 自动回退系统：桌面应用不可用时自动切换到Web UI
  • 现代界面：专业设计，标签页导航
  • 实时更新：与后端的WebSocket通信
  • 零依赖：只需要uv + ODBC驱动

工作原理

  1. 首选方案：使用预编译的桌面二进制文件（如果可用）
  2. 智能回退：桌面应用不可用时自动启动Web UI
  3. 零维护：用户无需安装或设置

📋 系统要求

所有平台：

  1. Python 3.11+
  2. ODBC Driver for SQL Server ⭐ 必需！
  3. uv（用于包执行）

Windows用户：

# 检查Python版本
python --version

# 检查ODBC驱动
python -c "import pyodbc; print([d for d in pyodbc.drivers() if 'SQL Server' in d])"

# 安装ODBC驱动（选择一种方法）：
# 方法1：winget（推荐）
winget install Microsoft.ODBCDriverforSQLServer

# 方法2：Chocolatey
choco install sqlserver-odbcdriver

🔧 Augment Code配置

方案1：完整设置（数据库+文件系统）

{
  "mcpServers": {
    "mcp-sqlserver-filesystem": {
      "command": "uvx",
      "args": ["mcp-sqlserver-filesystem@latest"],
      "timeout": 600,
      "env": {
        "DB_SERVER": "localhost",
        "DB_DATABASE": "your_database",
        "DB_USE_WINDOWS_AUTH": "true", 
        "DB_TRUST_SERVER_CERTIFICATE": "true",
        "FS_ALLOWED_PATHS": "C:\\Users\\YourName\\Documents,D:\\Projects",
        "FS_ALLOWED_EXTENSIONS": ".txt,.md,.py,.json,.sql,.csv",
        "FS_IGNORE_FILE_LOCKS": "true"
      },
      "autoApprove": [
        "sql_query", "list_tables", "get_table_schema",
        "read_file", "write_file", "list_directory"
      ]
    }
  }
}

方案2：SQL Server认证 + 文件系统全访问

{
  "mcpServers": {
    "mcp-sqlserver-filesystem": {
      "command": "uvx",
      "args": ["mcp-sqlserver-filesystem@latest"],
      "timeout": 600, 
      "env": {
        "DB_SERVER": "your-server",
        "DB_DATABASE": "your_database",
        "DB_USE_WINDOWS_AUTH": "false",
        "DB_USERNAME": "sa",
        "DB_PASSWORD": "your_password",
        "FS_ALLOWED_PATHS": "*",
        "FS_ALLOWED_EXTENSIONS": "*.*",
        "FS_IGNORE_FILE_LOCKS": "true"
      },
      "autoApprove": [
        "sql_query", "list_tables", "get_table_schema",
        "read_file", "write_file", "list_directory"
      ]
    }
  }
}

方案3：安全限制模式（生产环境）

{
  "mcpServers": {
    "mcp-sqlserver-filesystem": {
      "command": "uvx",
      "args": ["mcp-sqlserver-filesystem@latest"],
      "timeout": 600,
      "env": {
        "DB_SERVER": "prod-server.company.com",
        "DB_DATABASE": "ProductionDB",
        "DB_USE_WINDOWS_AUTH": "false", 
        "DB_USERNAME": "readonly_user",
        "DB_PASSWORD": "secure_password",
        "FS_ALLOWED_PATHS": "C:\\Projects\\Safe,D:\\Data\\ReadOnly",
        "FS_ALLOWED_EXTENSIONS": ".txt,.log,.json,.csv",
        "FS_ENABLE_WRITE": "false",
        "FS_ENABLE_DELETE": "false",
        "SEC_ENABLE_SQL_PROTECTION": "true"
      },
      "autoApprove": [
        "sql_query", "list_tables", "get_table_schema",
        "read_file", "list_directory"
      ]
    }
  }
}

🛠️ 环境变量

数据库配置

变量 默认值 描述
DB_SERVER localhost SQL Server主机名或IP
DB_DATABASE master 数据库名称
DB_USE_WINDOWS_AUTH true 使用Windows认证
DB_USERNAME - SQL Server用户名（非Windows认证时）
DB_PASSWORD - SQL Server密码（非Windows认证时）
DB_TRUST_SERVER_CERTIFICATE true 信任服务器证书
DB_ENCRYPT false 启用连接加密
DB_MULTIPLE_ACTIVE_RESULT_SETS true 启用MARS

文件系统配置

变量 默认值 描述
FS_ALLOWED_PATHS [] 允许的基路径（空或* = 允许全部）
FS_ALLOWED_EXTENSIONS [] 允许的文件扩展名（空或*.* = 允许全部）
FS_ENABLE_WRITE true 启用写操作
FS_ENABLE_DELETE true 启用删除操作
FS_IGNORE_FILE_LOCKS true 忽略文件锁定，提高兼容性
FS_MAX_FILE_SIZE 1073741824 最大文件大小（1GB）

安全配置

变量 默认值 描述
SEC_ENABLE_SQL_PROTECTION false 启用SQL注入保护
SEC_MAX_QUERY_LENGTH 100000 最大SQL查询长度
SEC_ENABLE_QUERY_LOGGING true 启用查询日志

📚 可用工具

数据库操作

  • sql_query - 执行SELECT查询，提供详细结果
  • list_tables - 列出所有数据库表
  • get_table_schema - 获取详细表结构信息

文件系统操作

  • read_file - 读取文件内容，自动检测编码
  • write_file - 写入文件内容，需要确认
  • list_directory - 列出目录内容及元数据

🎯 使用示例

带详细跟踪的SQL操作

# 执行查询 - 显示列名、数据类型和行数
result = sql_query("SELECT TOP 10 * FROM users ORDER BY created_date DESC")

# INSERT操作 - 显示插入的具体记录
result = sql_query("INSERT INTO users (name, email) VALUES ('John', 'john@example.com')")

# UPDATE操作 - 显示更新前后的受影响记录
result = sql_query("UPDATE users SET status = 'active' WHERE last_login > '2024-01-01'")

# DELETE操作 - 显示删除的具体记录
result = sql_query("DELETE FROM users WHERE status = 'inactive'")

带安全控制的文件系统操作

# 读取文件（支持被锁定的文件）
content = read_file("C:/Projects/config.json")

# 写入文件并确认
write_file("C:/Projects/output.txt", "Hello World!")

# 列出目录及元数据
files = list_directory("C:/Projects")

🔧 开发设置（可选）

仅在希望贡献代码或从源码构建时需要：

# 克隆仓库
git clone https://github.com/ppengit/mcp-sqlserver-filesystem.git
cd mcp-sqlserver-filesystem

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
python -m pytest

# 从源码运行
python -m mcp_sqlserver_filesystem --test-web

🚨 故障排除

常见问题

  1. "No module named 'pyodbc'"

    # 先安装ODBC驱动，然后重试
winget install Microsoft.ODBCDriverforSQLServer

  2. 连接超时问题

    "env": {
  "DB_CONNECTION_TIMEOUT": "60",
  "DB_COMMAND_TIMEOUT": "120"
}

  3. 桌面应用无法启动

    • 没问题！系统会自动回退到Web UI
    • 检查浏览器是否在http://localhost:8765打开

  4. 文件访问被拒绝

    "env": {
  "FS_IGNORE_FILE_LOCKS": "true"
}

📖 更多信息

License

MIT License - see LICENSE file for details.

Author

PJ - peng.it@qq.com

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for penjay from gravatar.com penjay

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: PJ
  • Tags cross-platform , database , desktop-app , dual-interface , filesystem , interactive , mcp , native-app , precompiled-binaries , sqlserver , web-ui
  • Requires: Python >=3.11
  • Provides-Extra: desktop , dev
Classifiers

Release history Release notifications | RSS feed

1.0.3

1.0.2

1.0.1

1.0.0

0.3.3

0.3.2

This version

0.3.1

0.3.0

0.2.9

0.2.8

0.2.7

0.2.6

0.2.5

0.2.4

0.2.3

0.2.2

0.2.1

0.2.0

0.1.7

0.1.6

0.1.5

0.1.4

0.1.2

0.1.1

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcp_sqlserver_filesystem-0.3.1.tar.gz (8.0 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mcp_sqlserver_filesystem-0.3.1-py3-none-any.whl (5.7 MB view details)

Uploaded Python 3

File details

Details for the file mcp_sqlserver_filesystem-0.3.1.tar.gz.

File metadata

File hashes

Hashes for mcp_sqlserver_filesystem-0.3.1.tar.gz
Algorithm Hash digest
SHA256 c6b3d8868589bf98094b174534980253f95965c89c3853fdbe64763846e585cd
MD5 bb4429012c5043fe47b7a7a31215fc42
BLAKE2b-256 69352bd8a60b1903481df957f7ea424857b6d85b762070cb2c9d9cdc90cd1fbe

See more details on using hashes here.

File details

Details for the file mcp_sqlserver_filesystem-0.3.1-py3-none-any.whl.

File metadata

File hashes

Hashes for mcp_sqlserver_filesystem-0.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 b1841c0029d1952b52c8b5c43ffdda386bddf00f809f0fcfa256351be08b0ad0
MD5 20f1606a7e1226b0b465208f47b8ef3a
BLAKE2b-256 77b574cf5e768131bb158b69cf3d6462818670f5ff93d4ed3d75d50a45e5cbf9

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page