一个高性能的文档转换服务器，同时支持 Model Context Protocol (MCP 模型上下文协议) 和 RESTful API 接口。将 PDF、Word 和 Excel 文档转换为 Markdown 格式，具备图片提取、页眉页脚移除和批量处理等高级功能。
📚 语言版本: English README | 中文说明
- MCP 协议：原生支持模型上下文协议和流式 HTTP 传输
- RESTful API：传统 HTTP API，配备 OpenAPI/Swagger 文档
- 统一后端：两种协议共享相同的转换逻辑
- PDF 转 Markdown：基于 marker-pdf 的高质量文本提取
- Word 转 Markdown：支持 .docx/.doc 格式，保持格式化
- Excel 转 Markdown：支持 .xlsx/.xls 格式，表格转换
- 批量处理：并发处理多个文档
- 图片提取：从文档中提取图片并通过静态 URL 提供服务
- 页眉页脚移除：智能移除重复的页面元素
- 多格式输出：Markdown、HTML 和 JSON 输出格式
- 结构分析：文档结构分析和验证
- 并发处理：高性能异步处理和速率限制
- Python 3.10 - 3.13（已验证 Python 3.13，暂不建议 3.14）
- 4GB+ 内存（用于 AI 模型）
- 10GB+ 磁盘空间（用于模型缓存）
# 克隆仓库
git clone https://github.com/WW-AI-Lab/any2markdown.git
cd any2markdown
# 创建虚拟环境（推荐使用 Python 3.13）
python3.13 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 准备环境变量文件
cp env.example .env
# 安装依赖（默认使用华为镜像）
PIP_CONFIG_FILE=.pip/pip.conf pip install -r requirements.txt
# 或一键安装
./scripts/setup_venv.sh# 使用预构建镜像直接启动服务
docker run -d \
-p 3000:3000 \
--name any2markdown-mcp-server \
--restart unless-stopped \
-v $(pwd)/uploads:/app/uploads \
-v $(pwd)/temp_images:/app/temp_images \
-v $(pwd)/logs:/app/logs \
-v $(pwd)/models:/root/.cache/marker \
-v $(pwd)/models/huggingface:/root/.cache/huggingface \
-v $(pwd)/models/torch:/root/.cache/torch \
-v $(pwd)/models/transformers:/root/.cache/transformers \
ccr.ccs.tencentyun.com/yfgaia/any2markdown-mcp-server:latest
# 💡 卷挂载说明：
# - uploads/: 上传文件存储
# - temp_images/: 临时图片缓存
# - logs/: 日志文件
# - models/: AI模型缓存（首次运行会自动下载，约3-5GB）
# 或使用部署脚本
./scripts/deploy.sh docker
# GPU 加速部署（需要 NVIDIA GPU）
./scripts/deploy.sh docker-gpu
# 自定义端口部署
./scripts/deploy.sh docker -p 8080
# 或直接使用 docker-compose：
docker-compose up -d any2markdown-mcp# 使用部署脚本启动服务器
./scripts/deploy.sh source
# 或手动启动：
python run_server.py
# 服务器将在以下地址可用：
# - MCP 协议：http://localhost:3000/mcp (流式 HTTP)
# - REST API：http://localhost:3000/api/v1/
# - API 文档：http://localhost:3000/api/v1/docs# 测试 RESTful API
python test_restful_api.py
# 测试 MCP 协议（官方 SDK，streamable-http）
python test_streamable_client.py ~/Downloads/测试翻译_1_1_translate.docx
# 检查服务状态
./scripts/deploy.sh status
# 停止服务
./scripts/deploy.sh stop📋 完整API文档: 详细的API设计和使用说明请参考 RESTful API 设计文档
📋 dify集成文档: 详细的dify集成文档请参考 dify集成文档
Any2Markdown 提供统一的RESTful API接口，支持两种调用方式：
# 文件上传方式 (推荐)
curl -X POST "http://localhost:3000/api/v1/convert" \
-F "file=@document.pdf" \
-F "extract_images=true" \
-F "include_content=false"
# JSON方式 (base64编码)
curl -X POST "http://localhost:3000/api/v1/convert" \
-H "Content-Type: application/json" \
-d '{
"files": [{
"filename": "document.pdf",
"file_content": "<base64编码的PDF>",
"options": {
"extract_images": true,
"include_content": false
}
}]
}'
# 查看系统状态
curl "http://localhost:3000/api/v1/status"
# 访问API文档
open http://localhost:3000/api/v1/docs- ✅ 统一端点: 单一
/api/v1/convert端点处理所有文档类型 - ✅ 双调用方式: 支持文件上传和base64 JSON两种方式
- ✅ 多文件处理: 支持批量转换多个文档
- ✅ 自动检测: 根据文件扩展名自动识别文档类型
- ✅ 丰富选项: 支持图片提取、页面范围、格式保留等选项
from mcp.client import ClientSession
from mcp.client.stdio import stdio_client
# 连接到 MCP 服务器
async with stdio_client() as (read, write):
async with ClientSession(read, write) as session:
# 转换 PDF 文档
result = await session.call_tool(
"convert_pdf_to_markdown",
{
"file_content": base64_pdf_content,
"filename": "document.pdf",
"extract_images": True,
"remove_header_footer": True
}
)
print(result.content)| 工具/端点 | 描述 | 输入格式 | 功能特性 |
|---|---|---|---|
convert_pdf_to_markdown |
PDF 转换，AI 驱动的文本提取 | OCR、布局检测、图片提取 | |
convert_word_to_markdown |
Word 文档转换 | DOCX, DOC | 格式保持、图片提取 |
convert_excel_to_markdown |
电子表格转换 | XLSX, XLS | 多工作表、公式支持 |
batch_convert_documents |
批量处理 | 混合格式 | 并发处理 |
analyze_pdf_structure |
文档结构分析 | 元数据提取 | |
validate_document |
文档验证 | 所有格式 | 格式验证 |
get_supported_formats |
列出支持的格式 | - | 功能发现 |
┌─────────────────────────┐ ┌─────────────────────────┐
│ MCP 客户端 │ │ HTTP 客户端 │
│ (Claude, IDE 等) │ │ (Web, Mobile 等) │
└─────────────────────────┘ └─────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────┐
│ Any2Markdown 服务器 │
├─────────────────────────┬───────────────────────────┤
│ MCP 协议 │ RESTful API │
│ (流式 HTTP) │ (OpenAPI/Swagger) │
└─────────────────────────┴───────────────────────────┘
│ │
└─────────────┬──────────────┘
▼
┌─────────────────────────────────────────────────────┐
│ 共享后端 │
├─────────────────────────────────────────────────────┤
│ 文档处理器 │ 模型管理器 │ 工具模块 │
│ ├─ PDF (marker) │ ├─ AI 模型 │ ├─ 文件 │
│ ├─ Word (python-docx)│ ├─ 缓存 │ ├─ 验证 │
│ └─ Excel (pandas) │ └─ 内存 │ └─ 图片 │
└─────────────────────────────────────────────────────┘
any2markdown/
├── 📚 docs/ # 文档
│ ├── README.md # 项目概述
│ ├── technical-design.md # 技术架构
│ ├── restful-api-design.md # API 规范
│ └── requirements.md # 需求分析
├── 💻 src/any2markdown_mcp/ # 源代码
│ ├── server.py # 主服务器 (MCP + FastAPI)
│ ├── config.py # 配置管理
│ ├── 🔧 tools/ # MCP 工具实现
│ │ ├── pdf_tools.py # PDF 转换工具
│ │ ├── word_tools.py # Word 转换工具
│ │ ├── excel_tools.py # Excel 转换工具
│ │ └── utility_tools.py # 实用工具
│ ├── 🌐 api/ # RESTful API 层
│ │ ├── handlers.py # API 端点
│ │ ├── models.py # Pydantic 模型
│ │ └── utils.py # API 工具
│ ├── ⚙️ processors/ # 文档处理器
│ │ ├── pdf_processor.py # PDF 处理逻辑
│ │ ├── word_processor.py # Word 处理逻辑
│ │ └── excel_processor.py # Excel 处理逻辑
│ └── 🧠 models/ # AI 模型管理
│ └── model_manager.py # 模型加载和缓存
├── 🧪 tests/ # 测试文件
├── 🚀 scripts/ # 部署脚本
│ └── deploy.sh # 统一部署脚本
├── 📋 requirements.txt # 依赖列表
├── 🏗️ pyproject.toml # 项目配置
├── 🐳 Dockerfile # Docker 配置
├── 🐳 docker-compose.yml # Docker Compose 配置
└── 🚀 run_server.py # 服务器启动脚本
# 服务器配置
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=3000
# 处理配置
MAX_CONCURRENT_JOBS=3
MAX_FILE_SIZE=100MB
TEMP_IMAGE_DIR=./temp_images
# 模型配置
MODEL_CACHE_DIR=~/.cache/marker
USE_GPU=true
# Hugging Face模型缓存配置
HF_HOME=~/.cache/huggingface
HF_HUB_CACHE=~/.cache/huggingface/hub
HF_ASSETS_CACHE=~/.cache/huggingface/assets
TORCH_HOME=~/.cache/torch
TRANSFORMERS_CACHE=~/.cache/transformers
# 模型下载配置
HF_HUB_ENABLE_HF_TRANSFER=false
HF_HUB_DISABLE_PROGRESS_BARS=false
HF_HUB_DISABLE_TELEMETRY=true
# 日志配置
LOG_LEVEL=INFO
LOG_FILE=logs/server.log
DEBUG=false# 基础部署
./scripts/deploy.sh source
# 开发模式，启用调试日志
./scripts/deploy.sh source --dev
# 自定义端口并禁用 GPU
./scripts/deploy.sh source -p 8080 --no-gpu
# 自定义环境文件
./scripts/deploy.sh source -e .env.production# 标准 Docker 部署
./scripts/deploy.sh docker
# GPU 加速部署（需要 NVIDIA Docker）
./scripts/deploy.sh docker-gpu
# 自定义端口
./scripts/deploy.sh docker -p 8080
# 开发模式
./scripts/deploy.sh docker --dev为了避免每次重启容器都重新下载模型，建议配置模型缓存目录挂载：
# 1. 初始化模型缓存目录结构
./scripts/setup_model_cache.sh
# 2. 使用 Docker Compose（推荐）
docker-compose up -d
# 3. 或者手动指定挂载目录
docker run -d \
-p 3000:3000 \
-v ./models/marker:/home/appuser/.cache/marker \
-v ./models/huggingface:/home/appuser/.cache/huggingface \
-v ./models/torch:/home/appuser/.cache/torch \
-v ./models/transformers:/home/appuser/.cache/transformers \
-v ./logs:/app/logs \
-v ./temp_images:/app/temp_images \
--name any2markdown \
any2markdown:latest模型缓存说明：
- 首次启动：系统会自动下载所需模型（约3-5GB），需要较长时间
- 后续启动：使用缓存的模型，启动速度显著提升
- 磁盘空间：建议预留至少10GB空间用于模型缓存
- 网络要求：需要能够访问 Hugging Face Hub
# 检查服务状态
./scripts/deploy.sh status
# 停止所有服务
./scripts/deploy.sh stop
# 清理资源
./scripts/deploy.sh cleanup创建 config.toml 或设置环境变量：
[server]
host = "0.0.0.0"
port = 3000
max_concurrent_jobs = 3
[processing]
max_file_size = "100MB"
temp_image_dir = "./temp_images"
enable_header_footer_removal = true
[models]
cache_dir = "~/.cache/marker"
enable_gpu = true
preload_models = true
# Hugging Face 模型缓存配置
hf_home = "~/.cache/huggingface"
hf_hub_cache = "~/.cache/huggingface/hub"
hf_assets_cache = "~/.cache/huggingface/assets"
torch_home = "~/.cache/torch"
transformers_cache = "~/.cache/transformers"
# 模型下载选项
hf_hub_enable_hf_transfer = false
hf_hub_disable_progress_bars = false
hf_hub_disable_telemetry = true
[logging]
level = "INFO"
file = "logs/server.log"# 运行所有测试
pytest
# 运行特定测试类别
pytest -m unit # 单元测试
pytest -m integration # 集成测试
pytest -m slow # 需要模型加载的测试
# 运行覆盖率测试
pytest --cov=src/any2markdown_mcp --cov-report=html
# 测试特定功能
python test_restful_api.py # REST API 测试
python test_streamable_client.py ~/Downloads/测试翻译_1_1_translate.docx # MCP 协议测试支持在dify工作流中集成，即通过dify 默认的http节点即可实现文件转换，具体方法查阅dify集成
- PDF 转换：~2-5 秒/页（使用 GPU）
- Word 转换：~0.5-2 秒/文档
- Excel 转换：~0.1-1 秒/工作表
- 并发请求：最多 3 个同时转换
- 内存使用：~2-4GB（模型加载后）
- 为 PDF 处理启用 GPU 加速
- 根据可用内存调整
MAX_CONCURRENT_JOBS - 为模型缓存使用 SSD 存储
- 为大型文档配置适当的超时值
我们欢迎贡献！请查看我们的贡献指南。
# 安装开发依赖
pip install -e ".[dev]"
# 安装 pre-commit 钩子
pre-commit install
# 运行代码质量检查
black src/ tests/
isort src/ tests/
mypy src/
flake8 src/
pytest- 在
src/any2markdown_mcp/processors/中创建处理器 - 在
src/any2markdown_mcp/tools/中添加 MCP 工具 - 在
src/any2markdown_mcp/api/中添加 API 端点 - 更新文档和测试
- 交互式 API 文档：http://localhost:3000/api/v1/docs
- OpenAPI 规范：http://localhost:3000/api/v1/openapi.json
- 技术设计：docs/technical-design.md
- API 设计：docs/restful-api-design.md
- 模型上下文协议 - 官方 MCP 规范
- marker-pdf - PDF 转 Markdown 转换
- python-docx - Word 文档处理
- FastAPI - 现代 Web 框架
本项目使用 MIT 许可证 - 详见 LICENSE 文件。
- 文档：docs/
- 问题反馈：GitHub Issues
- 讨论：GitHub Discussions
- 支持 PowerPoint (PPTX) 转换
- 图片类型PDF转换效果优化
- Kubernetes 部署清单
- 云存储集成
