# MCP SQL Server Filesystem
[English](README_EN.md) | 中文
一个简洁高效的 MCP (Model Context Protocol) 服务器，提供 SQL Server 数据库访问和文件系统操作功能。
## ✨ 主要特性
### 🗄️ 数据库功能
- **SQL 查询执行** - 支持 SELECT 查询
- **SQL 命令执行** - 支持 INSERT/UPDATE/DELETE 操作
- **表结构查询** - 获取表的详细结构信息和字段描述
- **表列表** - 列出数据库中的所有表
### 📁 文件系统功能
- **文件读取** - 读取文件内容
- **文件写入** - 写入内容到文件
- **目录列表** - 列出目录内容
### 🔒 安全特性
- SQL 注入防护
- 文件系统访问控制
- 环境变量配置
- 权限验证
## 🚀 快速开始
### 📋 前置要求
#### 1. 安装 ODBC Driver for SQL Server
**Windows:**
```bash
# 下载并安装 Microsoft ODBC Driver 17 for SQL Server
# 访问: https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server
# 或使用 winget 安装
winget install Microsoft.ODBCDriverforSQLServer
```
**macOS:**
```bash
# 使用 Homebrew 安装
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install msodbcsql17 mssql-tools
```
**Linux (Ubuntu/Debian):**
```bash
# 添加 Microsoft 仓库
curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -
curl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list
# 安装驱动
sudo apt-get update
sudo apt-get install msodbcsql17
```
#### 2. 验证 ODBC 安装
```bash
# Windows
odbcad32.exe
# macOS/Linux
odbcinst -j
```
### 📦 零安装使用（推荐）
```bash
# 安装 uv（如果尚未安装）
pip install uv
# 直接运行 - 无需克隆仓库！
uvx mcp-sqlserver-filesystem@latest
```
### 🔧 配置
在你的 MCP 客户端（如 Claude Desktop、AugmentCode）中添加以下配置：
```json
{
"mcpServers": {
"mcp-sqlserver-filesystem": {
"command": "uvx",
"args": ["mcp-sqlserver-filesystem@latest"],
"env": {
"DB_SERVER": "localhost",
"DB_DATABASE": "your_database",
"DB_USERNAME": "your_username",
"DB_PASSWORD": "your_password",
"DB_USE_WINDOWS_AUTH": "false",
"DB_TRUST_SERVER_CERTIFICATE": "true",
"DB_ENCRYPT": "false",
"FS_ALLOWED_PATHS": "*",
"FS_ALLOWED_EXTENSIONS": "*.*",
"FS_IGNORE_FILE_LOCKS": "true"
}
}
}
}
```
## 🛠️ 可用工具
### 数据库工具
- `sql_query` - 执行 SQL SELECT 查询
- `sql_execute` - 执行 SQL INSERT/UPDATE/DELETE 命令
- `list_tables` - 列出数据库中的所有表
- `get_table_schema` - 获取表的结构信息
### 文件系统工具
- `read_file` - 读取文件内容
- `write_file` - 写入文件内容
- `list_directory` - 列出目录内容
## 📋 环境变量
### 数据库配置
- `DB_SERVER` - SQL Server 服务器地址
- `DB_DATABASE` - 数据库名称
- `DB_USERNAME` - 用户名
- `DB_PASSWORD` - 密码
- `DB_USE_WINDOWS_AUTH` - 是否使用 Windows 身份验证
- `DB_TRUST_SERVER_CERTIFICATE` - 是否信任服务器证书
- `DB_ENCRYPT` - 是否加密连接
### 文件系统配置
- `FS_ALLOWED_PATHS` - 允许访问的路径（`*` 表示所有路径）
- `FS_ALLOWED_EXTENSIONS` - 允许的文件扩展名（`*.*` 表示所有文件）
- `FS_IGNORE_FILE_LOCKS` - 是否忽略文件锁
## 🔧 开发
### 本地开发
```bash
# 克隆仓库
git clone https://github.com/ppengit/mcp-sqlserver-filesystem.git
cd mcp-sqlserver-filesystem
# 安装依赖
uv sync
# 运行服务器
uv run python -m mcp_sqlserver_filesystem server
```
### 测试
```bash
# 运行测试
uv run pytest
# 运行特定测试
uv run pytest tests/test_database.py
```
## 📄 许可证
MIT License - 详见 [LICENSE](LICENSE) 文件。
## 🤝 贡献
欢迎贡献！请提交 Issue 或 Pull Request。
## ❓ 常见问题
### Q: 出现 "No module named 'pyodbc'" 错误
A: 请确保已安装 ODBC Driver for SQL Server，参见上面的前置要求部分。
### Q: 出现 "Data source name not found" 错误
A: 检查 `DB_SERVER` 配置是否正确，确保 SQL Server 服务正在运行。
### Q: 连接超时或拒绝连接
A:
1. 检查 SQL Server 是否启用了 TCP/IP 协议
2. 确认防火墙设置允许连接到 SQL Server 端口（默认1433）
3. 验证用户名和密码是否正确
### Q: 文件系统操作被拒绝
A: 检查 `FS_ALLOWED_PATHS` 和 `FS_ALLOWED_EXTENSIONS` 配置，确保路径和文件类型被允许访问。
## 📞 支持
- GitHub Issues: [https://github.com/ppengit/mcp-sqlserver-filesystem/issues](https://github.com/ppengit/mcp-sqlserver-filesystem/issues)
## 🔄 更新日志
### v1.0.1
- 🎉 首个稳定版本发布
- ✨ 完整的 SQL Server 数据库支持
- 📁 全面的文件系统操作
- 🔒 增强的安全特性
- 📝 改进的错误处理和日志记录
- 🚀 简化的架构，专注于核心功能
---
**注意**: 此版本专注于核心功能的稳定性和可靠性，提供简洁高效的MCP服务器体验。
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-sqlserver-filesystem",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cross-platform, database, filesystem, mcp, server, sqlserver",
"author": null,
"author_email": "PJ <peng.it@qq.com>",
"download_url": "https://files.pythonhosted.org/packages/3a/6a/9050c006d394237416e8da4b5928fae725a03d9027f05294ab8763b23ce6/mcp_sqlserver_filesystem-1.0.2.tar.gz",
"platform": null,
"description": "# MCP SQL Server Filesystem\n\n[English](README_EN.md) | \u4e2d\u6587\n\n\u4e00\u4e2a\u7b80\u6d01\u9ad8\u6548\u7684 MCP (Model Context Protocol) \u670d\u52a1\u5668\uff0c\u63d0\u4f9b SQL Server \u6570\u636e\u5e93\u8bbf\u95ee\u548c\u6587\u4ef6\u7cfb\u7edf\u64cd\u4f5c\u529f\u80fd\u3002\n\n## \u2728 \u4e3b\u8981\u7279\u6027\n\n### \ud83d\uddc4\ufe0f \u6570\u636e\u5e93\u529f\u80fd\n- **SQL \u67e5\u8be2\u6267\u884c** - \u652f\u6301 SELECT \u67e5\u8be2\n- **SQL \u547d\u4ee4\u6267\u884c** - \u652f\u6301 INSERT/UPDATE/DELETE \u64cd\u4f5c\n- **\u8868\u7ed3\u6784\u67e5\u8be2** - \u83b7\u53d6\u8868\u7684\u8be6\u7ec6\u7ed3\u6784\u4fe1\u606f\u548c\u5b57\u6bb5\u63cf\u8ff0\n- **\u8868\u5217\u8868** - \u5217\u51fa\u6570\u636e\u5e93\u4e2d\u7684\u6240\u6709\u8868\n\n### \ud83d\udcc1 \u6587\u4ef6\u7cfb\u7edf\u529f\u80fd\n- **\u6587\u4ef6\u8bfb\u53d6** - \u8bfb\u53d6\u6587\u4ef6\u5185\u5bb9\n- **\u6587\u4ef6\u5199\u5165** - \u5199\u5165\u5185\u5bb9\u5230\u6587\u4ef6\n- **\u76ee\u5f55\u5217\u8868** - \u5217\u51fa\u76ee\u5f55\u5185\u5bb9\n\n### \ud83d\udd12 \u5b89\u5168\u7279\u6027\n- SQL \u6ce8\u5165\u9632\u62a4\n- \u6587\u4ef6\u7cfb\u7edf\u8bbf\u95ee\u63a7\u5236\n- \u73af\u5883\u53d8\u91cf\u914d\u7f6e\n- \u6743\u9650\u9a8c\u8bc1\n\n## \ud83d\ude80 \u5feb\u901f\u5f00\u59cb\n\n### \ud83d\udccb \u524d\u7f6e\u8981\u6c42\n\n#### 1. \u5b89\u88c5 ODBC Driver for SQL Server\n\n**Windows:**\n```bash\n# \u4e0b\u8f7d\u5e76\u5b89\u88c5 Microsoft ODBC Driver 17 for SQL Server\n# \u8bbf\u95ee: https://docs.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server\n# \u6216\u4f7f\u7528 winget \u5b89\u88c5\nwinget install Microsoft.ODBCDriverforSQLServer\n```\n\n**macOS:**\n```bash\n# \u4f7f\u7528 Homebrew \u5b89\u88c5\nbrew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release\nbrew update\nbrew install msodbcsql17 mssql-tools\n```\n\n**Linux (Ubuntu/Debian):**\n```bash\n# \u6dfb\u52a0 Microsoft \u4ed3\u5e93\ncurl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add -\ncurl https://packages.microsoft.com/config/ubuntu/20.04/prod.list | sudo tee /etc/apt/sources.list.d/msprod.list\n\n# \u5b89\u88c5\u9a71\u52a8\nsudo apt-get update\nsudo apt-get install msodbcsql17\n```\n\n#### 2. \u9a8c\u8bc1 ODBC \u5b89\u88c5\n\n```bash\n# Windows\nodbcad32.exe\n\n# macOS/Linux\nodbcinst -j\n```\n\n### \ud83d\udce6 \u96f6\u5b89\u88c5\u4f7f\u7528\uff08\u63a8\u8350\uff09\n\n```bash\n# \u5b89\u88c5 uv\uff08\u5982\u679c\u5c1a\u672a\u5b89\u88c5\uff09\npip install uv\n\n# \u76f4\u63a5\u8fd0\u884c - \u65e0\u9700\u514b\u9686\u4ed3\u5e93\uff01\nuvx mcp-sqlserver-filesystem@latest\n```\n\n### \ud83d\udd27 \u914d\u7f6e\n\n\u5728\u4f60\u7684 MCP \u5ba2\u6237\u7aef\uff08\u5982 Claude Desktop\u3001AugmentCode\uff09\u4e2d\u6dfb\u52a0\u4ee5\u4e0b\u914d\u7f6e\uff1a\n\n```json\n{\n \"mcpServers\": {\n \"mcp-sqlserver-filesystem\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-sqlserver-filesystem@latest\"],\n \"env\": {\n \"DB_SERVER\": \"localhost\",\n \"DB_DATABASE\": \"your_database\",\n \"DB_USERNAME\": \"your_username\",\n \"DB_PASSWORD\": \"your_password\",\n \"DB_USE_WINDOWS_AUTH\": \"false\",\n \"DB_TRUST_SERVER_CERTIFICATE\": \"true\",\n \"DB_ENCRYPT\": \"false\",\n \"FS_ALLOWED_PATHS\": \"*\",\n \"FS_ALLOWED_EXTENSIONS\": \"*.*\",\n \"FS_IGNORE_FILE_LOCKS\": \"true\"\n }\n }\n }\n}\n```\n\n## \ud83d\udee0\ufe0f \u53ef\u7528\u5de5\u5177\n\n### \u6570\u636e\u5e93\u5de5\u5177\n\n- `sql_query` - \u6267\u884c SQL SELECT \u67e5\u8be2\n- `sql_execute` - \u6267\u884c SQL INSERT/UPDATE/DELETE \u547d\u4ee4\n- `list_tables` - \u5217\u51fa\u6570\u636e\u5e93\u4e2d\u7684\u6240\u6709\u8868\n- `get_table_schema` - \u83b7\u53d6\u8868\u7684\u7ed3\u6784\u4fe1\u606f\n\n### \u6587\u4ef6\u7cfb\u7edf\u5de5\u5177\n\n- `read_file` - \u8bfb\u53d6\u6587\u4ef6\u5185\u5bb9\n- `write_file` - \u5199\u5165\u6587\u4ef6\u5185\u5bb9\n- `list_directory` - \u5217\u51fa\u76ee\u5f55\u5185\u5bb9\n\n## \ud83d\udccb \u73af\u5883\u53d8\u91cf\n\n### \u6570\u636e\u5e93\u914d\u7f6e\n- `DB_SERVER` - SQL Server \u670d\u52a1\u5668\u5730\u5740\n- `DB_DATABASE` - \u6570\u636e\u5e93\u540d\u79f0\n- `DB_USERNAME` - \u7528\u6237\u540d\n- `DB_PASSWORD` - \u5bc6\u7801\n- `DB_USE_WINDOWS_AUTH` - \u662f\u5426\u4f7f\u7528 Windows \u8eab\u4efd\u9a8c\u8bc1\n- `DB_TRUST_SERVER_CERTIFICATE` - \u662f\u5426\u4fe1\u4efb\u670d\u52a1\u5668\u8bc1\u4e66\n- `DB_ENCRYPT` - \u662f\u5426\u52a0\u5bc6\u8fde\u63a5\n\n### \u6587\u4ef6\u7cfb\u7edf\u914d\u7f6e\n- `FS_ALLOWED_PATHS` - \u5141\u8bb8\u8bbf\u95ee\u7684\u8def\u5f84\uff08`*` \u8868\u793a\u6240\u6709\u8def\u5f84\uff09\n- `FS_ALLOWED_EXTENSIONS` - \u5141\u8bb8\u7684\u6587\u4ef6\u6269\u5c55\u540d\uff08`*.*` \u8868\u793a\u6240\u6709\u6587\u4ef6\uff09\n- `FS_IGNORE_FILE_LOCKS` - \u662f\u5426\u5ffd\u7565\u6587\u4ef6\u9501\n\n## \ud83d\udd27 \u5f00\u53d1\n\n### \u672c\u5730\u5f00\u53d1\n\n```bash\n# \u514b\u9686\u4ed3\u5e93\ngit clone https://github.com/ppengit/mcp-sqlserver-filesystem.git\ncd mcp-sqlserver-filesystem\n\n# \u5b89\u88c5\u4f9d\u8d56\nuv sync\n\n# \u8fd0\u884c\u670d\u52a1\u5668\nuv run python -m mcp_sqlserver_filesystem server\n```\n\n### \u6d4b\u8bd5\n\n```bash\n# \u8fd0\u884c\u6d4b\u8bd5\nuv run pytest\n\n# \u8fd0\u884c\u7279\u5b9a\u6d4b\u8bd5\nuv run pytest tests/test_database.py\n```\n\n## \ud83d\udcc4 \u8bb8\u53ef\u8bc1\n\nMIT License - \u8be6\u89c1 [LICENSE](LICENSE) \u6587\u4ef6\u3002\n\n## \ud83e\udd1d \u8d21\u732e\n\n\u6b22\u8fce\u8d21\u732e\uff01\u8bf7\u63d0\u4ea4 Issue \u6216 Pull Request\u3002\n\n## \u2753 \u5e38\u89c1\u95ee\u9898\n\n### Q: \u51fa\u73b0 \"No module named 'pyodbc'\" \u9519\u8bef\nA: \u8bf7\u786e\u4fdd\u5df2\u5b89\u88c5 ODBC Driver for SQL Server\uff0c\u53c2\u89c1\u4e0a\u9762\u7684\u524d\u7f6e\u8981\u6c42\u90e8\u5206\u3002\n\n### Q: \u51fa\u73b0 \"Data source name not found\" \u9519\u8bef\nA: \u68c0\u67e5 `DB_SERVER` \u914d\u7f6e\u662f\u5426\u6b63\u786e\uff0c\u786e\u4fdd SQL Server \u670d\u52a1\u6b63\u5728\u8fd0\u884c\u3002\n\n### Q: \u8fde\u63a5\u8d85\u65f6\u6216\u62d2\u7edd\u8fde\u63a5\nA:\n1. \u68c0\u67e5 SQL Server \u662f\u5426\u542f\u7528\u4e86 TCP/IP \u534f\u8bae\n2. \u786e\u8ba4\u9632\u706b\u5899\u8bbe\u7f6e\u5141\u8bb8\u8fde\u63a5\u5230 SQL Server \u7aef\u53e3\uff08\u9ed8\u8ba41433\uff09\n3. \u9a8c\u8bc1\u7528\u6237\u540d\u548c\u5bc6\u7801\u662f\u5426\u6b63\u786e\n\n### Q: \u6587\u4ef6\u7cfb\u7edf\u64cd\u4f5c\u88ab\u62d2\u7edd\nA: \u68c0\u67e5 `FS_ALLOWED_PATHS` \u548c `FS_ALLOWED_EXTENSIONS` \u914d\u7f6e\uff0c\u786e\u4fdd\u8def\u5f84\u548c\u6587\u4ef6\u7c7b\u578b\u88ab\u5141\u8bb8\u8bbf\u95ee\u3002\n\n## \ud83d\udcde \u652f\u6301\n\n- GitHub Issues: [https://github.com/ppengit/mcp-sqlserver-filesystem/issues](https://github.com/ppengit/mcp-sqlserver-filesystem/issues)\n\n## \ud83d\udd04 \u66f4\u65b0\u65e5\u5fd7\n\n### v1.0.1\n- \ud83c\udf89 \u9996\u4e2a\u7a33\u5b9a\u7248\u672c\u53d1\u5e03\n- \u2728 \u5b8c\u6574\u7684 SQL Server \u6570\u636e\u5e93\u652f\u6301\n- \ud83d\udcc1 \u5168\u9762\u7684\u6587\u4ef6\u7cfb\u7edf\u64cd\u4f5c\n- \ud83d\udd12 \u589e\u5f3a\u7684\u5b89\u5168\u7279\u6027\n- \ud83d\udcdd \u6539\u8fdb\u7684\u9519\u8bef\u5904\u7406\u548c\u65e5\u5fd7\u8bb0\u5f55\n- \ud83d\ude80 \u7b80\u5316\u7684\u67b6\u6784\uff0c\u4e13\u6ce8\u4e8e\u6838\u5fc3\u529f\u80fd\n\n---\n\n**\u6ce8\u610f**: \u6b64\u7248\u672c\u4e13\u6ce8\u4e8e\u6838\u5fc3\u529f\u80fd\u7684\u7a33\u5b9a\u6027\u548c\u53ef\u9760\u6027\uff0c\u63d0\u4f9b\u7b80\u6d01\u9ad8\u6548\u7684MCP\u670d\u52a1\u5668\u4f53\u9a8c\u3002\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple and efficient MCP server for SQL Server database access and filesystem operations",
"version": "1.0.2",
"project_urls": {
"Homepage": "https://github.com/ppengit/mcp-sqlserver-filesystem",
"Issues": "https://github.com/ppengit/mcp-sqlserver-filesystem/issues",
"Repository": "https://github.com/ppengit/mcp-sqlserver-filesystem"
},
"split_keywords": [
"cross-platform",
" database",
" filesystem",
" mcp",
" server",
" sqlserver"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d584ac4ab619e61968200eeb984128c20017cf187a5a3d48510a9f9f8b1ccc72",
"md5": "90b711d5a4972a3cf0d3c85cf6a9900c",
"sha256": "0120d68f202d9eedf1711f520a30f6571efa3656ecc0863a7cb87045745aed1e"
},
"downloads": -1,
"filename": "mcp_sqlserver_filesystem-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "90b711d5a4972a3cf0d3c85cf6a9900c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 23009,
"upload_time": "2025-08-24T11:32:00",
"upload_time_iso_8601": "2025-08-24T11:32:00.555863Z",
"url": "https://files.pythonhosted.org/packages/d5/84/ac4ab619e61968200eeb984128c20017cf187a5a3d48510a9f9f8b1ccc72/mcp_sqlserver_filesystem-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3a6a9050c006d394237416e8da4b5928fae725a03d9027f05294ab8763b23ce6",
"md5": "b4ddb5d8bb75f2406d8c1d3b56b41bf3",
"sha256": "d3e739ec2f71d35cb5b876ffda81da259cba5b91932c3b8825e47ddb944c07db"
},
"downloads": -1,
"filename": "mcp_sqlserver_filesystem-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "b4ddb5d8bb75f2406d8c1d3b56b41bf3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 20355,
"upload_time": "2025-08-24T11:32:01",
"upload_time_iso_8601": "2025-08-24T11:32:01.688685Z",
"url": "https://files.pythonhosted.org/packages/3a/6a/9050c006d394237416e8da4b5928fae725a03d9027f05294ab8763b23ce6/mcp_sqlserver_filesystem-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 11:32:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ppengit",
"github_project": "mcp-sqlserver-filesystem",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mcp-sqlserver-filesystem"
}
JSON
