Any2Markdown MCP 服务器

一个高性能的文档转换服务器，同时支持 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 部署（推荐，开箱即用）

# 使用预构建镜像直接启动服务
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

📖 使用示例

RESTful API

📋 完整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两种方式
• ✅ 多文件处理: 支持批量转换多个文档
• ✅ 自动检测: 根据文件扩展名自动识别文档类型
• ✅ 丰富选项: 支持图片提取、页面范围、格式保留等选项

MCP 协议

from mcp.client import ClientSession
from mcp.client.stdio import stdio_client

... [View full README on GitHub](https://github.com/WW-AI-Lab/any2markdown#readme)