unifiles-mcp

MCP server for unifiles - unified file operations library.

简介

unifiles-mcp 是一个基于 MCP Python SDK 官方 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+

安装

从源码安装（开发模式，含测试与类型检查等依赖）：

git clone https://github.com/Asheng008/unifiles-mcp.git
cd unifiles-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

仅安装运行依赖：

pip install -e .

使用依赖锁文件安装（推荐用于生产环境）：

pip install -r requirements.txt

若已发布到 PyPI：

pip install unifiles-mcp

快速开始

启动服务器

安装后可在终端直接运行：

unifiles-mcp

或从代码启动：

from unifiles_mcp.main import mcp

if __name__ == "__main__":
    mcp.run()

使用 MCP 客户端连接

服务器启动后，可通过 MCP 客户端连接使用。以下为常见客户端的配置方式。

Cursor

在项目或用户配置的 .cursor/mcp.json 中加入（使用 PyPI 已发布包，需已安装 uv）：

{
  "mcpServers": {
    "unifiles-mcp": {
      "command": "uvx",
      "args": ["unifiles-mcp"]
    }
  }
}

使用本地开发环境时，可改为指定 venv 中的 Python 与模块（将 D:\path\to\unifiles-mcp 替换为你的项目根目录）：

"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 文件操作

# 1. 检查 Excel 文件结构
result = await excel_inspect_file(
    file_path="data.xlsx",
    include_preview=True,
    preview_rows=3
)
# 返回：文件信息，包括所有工作表名称、列名和预览数据

# 2. 读取工作表内容
result = await excel_read_sheet(
    file_path="data.xlsx",
    sheet_name="Sheet1"
)
# 返回：JSON 格式的工作表数据

SQLite 数据库操作

# 1. 检查数据库结构
result = await sqlite_inspect_database(
    db_path="database.db",
    include_preview=True
)
# 返回：数据库信息，包括所有表的结构和数据预览

# 2. 获取表结构
result = await sqlite_get_schema(
    db_path="database.db",
    table_name="users"
)
# 返回：字段名到类型的映射

# 3. 执行查询
result = await sqlite_query(
    db_path="database.db",
    sql="SELECT * FROM users WHERE age > :age",
    params={"age": 18}
)
# 返回：JSON 格式的查询结果

PDF 文本提取

# 提取所有页面
result = await pdf_extract_text(
    file_path="document.pdf"
)

# 提取指定页面范围
result = await pdf_extract_text(
    file_path="document.pdf",
    page_range=(1, 5)  # 第 1 到第 5 页
)

Word 文档操作

# 1. 检查文档结构（上帝视角）
result = await word_inspect_document(
    file_path="document.docx",
    extract_images=False
)
# 返回：段落数、表格数、图片数等统计信息

# 2. 提取完整文本
result = await word_extract_text(
    file_path="document.docx"
)
# 返回：文档完整文本（表格转为 Markdown）

# 3. 提取表格
result = await word_extract_tables(
    file_path="document.docx",
    output_format="md"
)
# 返回：Markdown 格式的表格

# 4. 写入文档
result = await word_write_document(
    content="文档内容",
    file_path="output.docx",
    title="文档标题"
)

核心工具（v0.1.3）

Excel 工具

• excel_inspect_file - 检查 Excel 文件结构（"上帝视角"）
• excel_read_sheet - 读取 Excel 工作表内容

PDF 工具

• pdf_extract_text - 提取 PDF 文本内容

Word 工具

• word_inspect_document - 综合检查文档元素（"上帝视角"）
• word_extract_text - 提取文档完整文本
• word_extract_tables - 提取文档中的表格
• word_extract_images - 提取文档中的图片
• word_write_document - 写入 Word 文档

SQLite 工具

• sqlite_inspect_database - 检查 SQLite 数据库（"上帝视角"）
• sqlite_get_schema - 获取表结构
• sqlite_query - 执行 SQL 查询

通用工具

• ping - 健康检查，返回 pong 表示服务运行中

开发

代码格式化与静态检查

# 激活虚拟环境
.\.venv\Scripts\Activate.ps1

# 使用 black 格式化代码
black src/

# 使用 ruff 检查代码
ruff check src/

类型检查

# 使用 mypy 进行类型检查
mypy src/unifiles_mcp/

项目结构

unifiles-mcp/
├── src/
│   └── unifiles_mcp/
│       ├── __init__.py
│       ├── main.py              # MCP 服务器入口
│       ├── tools/               # MCP 工具
│       │   ├── __init__.py
│       │   ├── excel.py
│       │   ├── pdf.py
│       │   ├── word/            # Word 工具包
│       │   │   ├── __init__.py
│       │   │   ├── inspect.py
│       │   │   ├── extract.py
│       │   │   └── write.py
│       │   └── sqlite.py
│       └── utils/               # 工具函数
│           ├── __init__.py
│           ├── async_wrapper.py
│           └── validators.py
├── docs/                       # 文档
│   ├── 01-API.md              # API 文档
│   ├── 02-PYPI_RELEASE_CHECKLIST.md
│   └── 03-TESTING.md
├── .opencode/                  # OpenCode 配置
│   └── rules/                  # 项目规则
├── .cursor/                    # Cursor IDE 配置（可选）
│   ├── commands/               # Cursor 命令
│   ├── rules/                  # 项目规则
│   ├── skills/                 # Cursor Skills
│   └── mcp.json                # MCP 配置
├── LICENSE                     # MIT 许可证
├── publish_pypi.bat            # Windows 发布脚本
├── publish_pypi.sh             # Linux/macOS 发布脚本
├── requirements.txt            # 生产依赖
├── requirements-dev.txt        # 开发依赖（可选）
├── pyproject.toml              # 项目配置
├── CHANGELOG.md                # 更新日志
├── HISTORY.md                  # 对话与变更历史
├── AGENTS.md                   # AI Agent 开发规范
└── README.md                   # 本文档

文档

序号	文档	说明
01	API.md	详细的工具 API 说明和使用示例
02	PYPI_RELEASE_CHECKLIST.md	发布到 PyPI 前的检查与步骤
03	TESTING.md	测试指南（单元测试与集成测试）

其他文档：

• 技术需求文档 - 项目技术需求
• 开发规范 - AI Agent 开发规范
• 更新日志 - 版本变更记录
• 历史记录 - 对话与变更历史

作者与维护者

• 作者：Asheng (w62745@qq.com)
• 仓库：https://github.com/Asheng008/unifiles-mcp
• 欢迎通过 Issues 或 Pull Request 参与贡献。

许可证

本项目采用 MIT License。

相关项目

• unifiles - 统一的文件操作库
• MCP Python SDK - Model Context Protocol 官方 Python SDK
• MCP 官方文档 - MCP Python SDK 完整文档