Skip to main content
Glama
unifiles-mcp

unifiles-mcp

by Asheng008

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 等多种文件格式的读取、写入、查询和管理。

Related MCP server: mcp-documents-reader

功能特性

  • ✅ 统一接口: 通过 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

测试指南(单元测试与集成测试)

其他文档:

作者与维护者

许可证

本项目采用 MIT License。

相关项目

Available Tools

12 tools
excel_inspect_fileA

检查 Excel 文件结构。

返回包含所有 Sheet 名称、列头和前几行数据预览的摘要信息。 在决定读取哪个 Sheet 之前,请先使用此工具。

Inputs: file_path (required), include_preview, preview_rows. Returns: object

excel_read_sheetB

读取 Excel 工作表内容并返回 JSON 格式的数据。

支持读取单个工作表。如果数据量大,返回结果可能被截断。

Inputs: file_path (required), sheet_name. Returns: result

pdf_extract_textA

从 PDF 文件中提取文本内容。

支持提取所有页面或指定页面范围的文本。页面之间用换行符分隔。

Inputs: file_path (required), page_range. Returns: result

pingA

Health check endpoint. Returns 'pong' if server is running.

Inputs: no named parameters. Returns: result

sqlite_get_schemaA

获取 SQLite 表结构(字段名到字段类型的映射)。

核心工具。LLM 写 SQL 前必须看 Schema。

Inputs: db_path (required), table_name (required). Returns: object

sqlite_inspect_databaseA

检查 SQLite 数据库结构。

返回包含所有表名称、表结构和前几行数据预览的摘要信息。 在决定查询哪个表之前,请先使用此工具。

Inputs: db_path (required), include_preview, preview_rows. Returns: object

sqlite_queryA

执行 SQL 查询并返回 JSON 格式的数据。

支持参数化查询,防止 SQL 注入。仅支持 SELECT 查询。

Inputs: db_path (required), sql (required), params. Returns: result

word_extract_imagesB

提取 Word 文档中的图片。

返回包含每张图片元信息的列表,字段包括 filename、path、width、height、format、size_bytes。

Inputs: file_path (required), output_dir. Returns: result

word_extract_tablesA

提取 Word 文档中的所有表格。

支持返回 Markdown 格式或二维列表格式的表格数据。

Inputs: file_path (required), output_format. Returns: result

word_extract_textA

提取 Word 文档完整文本。

段落和表格按文档顺序输出,表格转换为 Markdown 格式。

Inputs: file_path (required). Returns: result

word_inspect_documentA

综合检查 Word 文档元素。

提取文档中的段落、表格和图片信息,返回综合统计结果。 在决定读取哪个部分之前,请先使用此工具。

Inputs: file_path (required), extract_images, image_dir. Returns: object

word_write_documentA

将内容写入 Word 文档。

创建新的 Word 文档并写入内容。如果提供了标题,会将标题作为文档标题添加。

Inputs: content (required), file_path (required), title. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a specific file type and action (e.g., inspect vs read for Excel, extract vs write for Word), with no overlapping purposes. The ping tool is distinct. Even complementary tools like sqlite_inspect_database and sqlite_get_schema have clear, separate roles.

    Naming Consistency4/5

    Tools use a consistent filetype_verb_noun pattern (e.g., excel_inspect_file, word_extract_text). The verb choice varies across file types (inspect, read, get, query, extract, write), but within each group the pattern is predictable. The lone ping tool lacks a prefix, breaking the pattern slightly.

    Tool Count5/5

    12 tools is well within the ideal range. Each file type has a focused set (Excel:2, PDF:1, SQLite:3, Word:5) that covers essential operations without overloading the server. No tool feels redundant or unnecessary.

    Completeness4/5

    The server covers inspection, reading, and extraction for Excel, PDF, SQLite, and Word, plus Word write. Missing write operations for Excel, PDF, and SQLite, but the server's focus seems read-only. There is no tool for CSV or other formats, but the current scope is reasonably complete.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to read, write, and manipulate Excel files through comprehensive spreadsheet operations. Supports file management, data querying, worksheet operations, formula calculations, and includes security features like path validation and automatic backups.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides three MCP servers for interacting with Excel files, PDF documents, and SQLite databases, enabling AI assistants to read, create, update, and analyze local resources.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to read, modify, and create Word (.docx) and Excel (.xlsx) files through natural language commands, including batch queries and temporary table management.
      MIT