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
  • 🌐 Web UI Interface - Real-time query results display with modern responsive design
  • 🖥️ Desktop Application - Cross-platform native desktop app with intelligent fallback to Web UI
  • 🔍 Smart Environment Detection - Auto-adapts to SSH Remote, WSL, Local environments
  • 🔐 Enhanced Connection Parameters - Built-in support for TrustServerCertificate=true, Encrypt=false, MultipleActiveResultSets=true
  • ⚡ Dual Interface Architecture - Choose between Web UI and native desktop experience
  • 🎨 Modern UI Design - Responsive design with professional styling
  • 🔄 Real-time Communication - WebSocket-based live updates
  • 📊 Detailed Operation Tracking - INSERT/UPDATE/DELETE operations show affected records

🚀 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 Both Interfaces

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

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

🖥️ 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命令，详细跟踪操作记录
  • 📁 全面文件系统访问 - 读写文件，支持高级安全控制
  • 🌐 Web UI界面 - 实时查询结果显示，现代响应式设计
  • 🖥️ 桌面应用程序 - 跨平台原生桌面应用，智能回退到Web UI
  • 🔍 智能环境检测 - 自动适配SSH远程、WSL、本地环境
  • 🔐 增强连接参数 - 内置支持TrustServerCertificate=true、Encrypt=false、MultipleActiveResultSets=true
  • ⚡ 双界面架构 - 在Web UI和原生桌面体验之间选择
  • 🎨 现代UI设计 - 响应式设计，专业样式
  • 🔄 实时通信 - 基于WebSocket的实时更新
  • 📊 详细操作跟踪 - INSERT/UPDATE/DELETE操作显示受影响的具体记录

🚀 快速开始

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

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

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

🧪 测试两种界面

# 测试Web UI（基于浏览器的界面）
uvx mcp-sqlserver-filesystem@latest --test-web

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

🖥️ 桌面应用

功能特性

  • 无需安装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

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

This version

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.2.0.tar.gz (399.8 kB 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.2.0-py3-none-any.whl (406.2 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: mcp_sqlserver_filesystem-0.2.0.tar.gz
  • Upload date:
  • Size: 399.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for mcp_sqlserver_filesystem-0.2.0.tar.gz
Algorithm Hash digest
SHA256 3ee66e7893475cba334cec41c5fccc50d6347ee5c23361d788fafc999e032782
MD5 7b175b9ded2d27146d8f0c3f0699ebb2
BLAKE2b-256 d900641c3ff5d80fda1b0269feeea691ba83756622b8992a71742296e82007d8

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for mcp_sqlserver_filesystem-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 efb08166e34e13959af133950c0ebc3be8a6fd63f470d64bbc1c7fc5ebf0d3eb
MD5 d87b1f4f89b8d2b7ab2206185cd4c37d
BLAKE2b-256 ec21b27ba3418dcc9a97da7fe34cc64f4a55dbfdbb17687fdde63eb9789db5b5

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