前言
在 AI 辅助编程的时代，OpenCode 作为一款强大的终端 AI 助手，能够帮助开发者完成各种编程任务。而 markitdown-mcp 则是一个基于 MCP (Model Context Protocol) 的服务，可以将各种资源（网页、文件、PDF 等）转换为 Markdown 格式，极大地扩展了 AI 的文档处理能力。
本文将详细介绍如何在 OpenCode 中配置和使用 markitdown-mcp。
什么是 markitdown-mcp？
markitdown-mcp 是一个轻量级的 MCP 服务器，支持 STDIO、Streamable HTTP 和 SSE 三种传输方式。它提供了一个核心工具：convert_to_markdown(uri)，可以将以下类型的资源转换为 Markdown：
- HTTP/HTTPS 网页
- 本地文件（file://）
- Data URI
安装步骤
1. 安装系统依赖
在安装 markitdown-mcp 之前，需要安装必要的系统工具和 Python 环境。
Debian/Ubuntu 系统
sudo apt update
sudo apt install -y python3 python3-pip python3-venv ffmpeg exiftool
macOS 系统
brew install python3 ffmpeg exiftool
Windows 系统
依赖说明
- ffmpeg: 用于处理音视频文件，支持将音视频内容提取转换为文本
- exiftool: 用于读取文件元数据信息，如图片的 EXIF 信息、PDF 的元数据等
2. 安装 markitdown Python 库
markitdown-mcp 发布在 PyPI 上，推荐安装完整版本以支持所有文件格式：
pip install "markitdown[all]"
markitdown[all] 会安装所有可选依赖，支持以下格式的文件转换：
- PDF 文档
- Office 文档（Word、Excel、PowerPoint）
- 音视频文件
- 图片文件
- HTML 网页
- 等等
推荐：使用 uv 工具安装
uv 是一个快速的 Python 包管理器，推荐使用：
uv pip install "markitdown[all]"
3. 安装 markitdown-mcp Python 库
markitdown-mcp 发布在 PyPI 上，推荐安装完整版本以支持所有文件格式：
pip install markitdown-mcp
markitdown[all] 会安装所有可选依赖，支持以下格式的文件转换：
- PDF 文档
- Office 文档（Word、Excel、PowerPoint）
- 音视频文件
- 图片文件
- HTML 网页
- 等等
推荐：使用 uv 工具安装
uv 是一个快速的 Python 包管理器，推荐使用：
uv pip install markitdown-mcp
或者使用 uvx 直接运行（无需全局安装）
uvx markitdown-mcp
3. 验证安装
安装完成后，可以验证是否安装成功：
markitdown-mcp --help
如果安装成功，会显示帮助信息。
OpenCode 配置
配置文件位置
OpenCode 的配置文件位于以下位置（按优先级排序）：
$HOME/.opencode.json或$HOME/.config/opencode/opencode.json./.opencode.json（项目目录）
配置 markitdown-mcp
打开 OpenCode 配置文件，在 mcp 配置块中添加 markitdown 配置：
{
"mcp": {
"markitdown": {
"type": "local",
"command": ["uvx", "markitdown-mcp"],
"enabled": true
}
}
}
配置说明
- type:
"local"表示使用本地 MCP 服务器 - command: 启动 MCP 服务器的命令，这里直接运行
markitdown-mcp - enabled:
true表示启用该 MCP 服务器
使用示例
配置完成后，重启 OpenCode，你就可以使用 markitdown 的功能了。
示例 1：转换网页为 Markdown
请帮我将这个网页转换为 Markdown：https://example.com/article
OpenCode 会调用 convert_to_markdown 工具，将网页内容转换为 Markdown 格式。
示例 2：转换本地 PDF 文件
请帮我将这个 PDF 文件转换为 Markdown：file:///path/to/document.pdf
示例 3：转换 Office 文档
请帮我将这个 Word 文档转换为 Markdown：file:///path/to/document.docx
示例 4：转换 Data URI
请帮我将这个 Data URI 转换为 Markdown：data:text/html,<h1>Hello World</h1>
高级配置
调试 MCP 服务器
如果遇到问题，可以使用 MCP Inspector 进行调试：
npx @modelcontextprotocol/inspector uvx markitdown-mcp
然后在浏览器中打开 http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=xxxx，选择 STDIO 传输方式，点击 Connect 进行调试。
常见问题
1. 找不到 markitdown-mcp 命令
原因：Python 的 bin 目录不在 PATH 环境变量中。
解决方案：
- 确保 Python bin 目录在 PATH 中
- 或使用完整路径：
/path/to/python/bin/markitdown-mcp
2. 音视频文件转换失败
原因：未安装 ffmpeg。
解决方案：
# Debian/Ubuntu
sudo apt install ffmpeg -y
# macOS
brew install ffmpeg
3. 文件元数据读取失败
原因：未安装 exiftool。
解决方案：
# Debian/Ubuntu
sudo apt install exiftool -y
# macOS
brew install exiftool
4. 本地文件无法访问
原因：权限问题或路径不正确。
解决方案：
- 确保文件路径正确
- 确保有读取权限
架构图
graph LR
A[OpenCode CLI] -->|MCP Protocol| B[markitdown-mcp]
B -->|HTTP/HTTPS| C[Web Pages]
B -->|file://| D[Local Files]
B -->|data://| E[Data URI]
B -->|Output| F[Markdown]
F -->|Return| A
支持的文件格式
通过 markitdown[all] 安装完整依赖后，支持以下格式：
| 类别 | 格式 |
|---|---|
| 文档 | PDF, DOCX, XLSX, PPTX |
| 网页 | HTML, HTM |
| 音频 | MP3, WAV, M4A, FLAC (需 ffmpeg) |
| 视频 | MP4, MKV, AVI, MOV (需 ffmpeg) |
| 图片 | PNG, JPG, JPEG, GIF, BMP |
| 数据 | JSON, CSV, XML |
| 其他 | TXT, MD, RTF, EPUB |
总结
通过本文的介绍，你应该已经掌握了：
- 如何安装系统依赖（ffmpeg、exiftool）
- 如何安装 markitdown-mcp 完整版
- 如何在 OpenCode 中配置 markitdown-mcp
- 如何进行调试和排查问题
markitdown-mcp 为 OpenCode 提供了强大的文档转换能力，让你可以轻松处理各种格式的文档，提高开发效率。