unifiles-mcp

# unifiles-mcp MCP server for [unifiles](https://github.com/Asheng008/unifiles) - unified file operations library. ## 简介 `unifiles-mcp` 是一个基于 [MCP Python SDK](https://pypi.org/project/mcp/) 官方 SDK 构建的 Model Context Protocol (MCP) 服务器，为 AI 助手提供统一的文件操作能力。它使用官方的 `FastMCP` 高级接口，封装了 `unifiles` 库的功能，支持 Excel、PDF、Word、SQLite 等多种文件格式的读取、写入、查询和管理。 ## 功能特性 - ✅ **统一接口**: 通过 MCP 协议提供标准化的文件操作接口 - ✅ **多格式支持**: Excel (.xlsx, .xls), PDF (.pdf), Word (.docx), SQLite (.db, .sqlite) - ✅ **类型安全**: 完整的类型注解，基于 Pydantic V2 - ✅ **异步优先**: 所有操作使用异步方式，提高性能 - ✅ **LLM 友好**: 优化的工具设计，减少调用次数 ## 环境要求 - **Python**: 3.10+ - **操作系统**: Windows 10+, Linux, macOS 10.14+ ## 安装 从源码安装（开发模式，含测试与类型检查等依赖）： ```powershell git clone https://github.com/Asheng008/unifiles-mcp.git cd unifiles-mcp python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -e ".[dev]" ``` 仅安装运行依赖： ```powershell pip install -e . ``` 使用依赖锁文件安装（推荐用于生产环境）： ```powershell pip install -r requirements.txt ``` 若已发布到 PyPI： ```bash pip install unifiles-mcp ``` ## 快速开始 ### 启动服务器 安装后可在终端直接运行： ```bash unifiles-mcp ``` 或从代码启动： ```python from unifiles_mcp.main import mcp if __name__ == "__main__": mcp.run() ``` ### 使用 MCP 客户端连接 服务器启动后，可通过 MCP 客户端连接使用。以下为常见客户端的配置方式。 #### Cursor 在项目或用户配置的 `.cursor/mcp.json` 中加入（使用 PyPI 已发布包，需已安装 [uv](https://docs.astral.sh/uv/)）： ```json { "mcpServers": { "unifiles-mcp": { "command": "uvx", "args": ["unifiles-mcp"] } } } ``` 使用本地开发环境时，可改为指定 venv 中的 Python 与模块（将 `D:\path\to\unifiles-mcp` 替换为你的项目根目录）： ```json "unifiles-mcp": { "command": "D:\\path\\to\\unifiles-mcp\\.venv\\Scripts\\python.exe", "args": ["-m", "unifiles_mcp.main"] } ``` #### Claude Desktop / 其他 MCP 客户端 在客户端的 MCP 配置文件中添加上述 `command` 与 `args`（或对应客户端的等价配置），指向 `unifiles-mcp` 或 `python -m unifiles_mcp.main` 即可。具体配置路径请参考各客户端的 MCP 文档。 ### 使用示例 #### Excel 文件操作 ```python # 1. 检查 Excel 文件结构 result = await excel_inspect_file( file_path="data.xlsx", include_preview=True, preview_rows=3…