MarkItDown MCP 服务器
一个模型上下文协议(MCP)服务器,它使用微软的MarkItDown库将各种文档格式转换为Markdown格式。
特点/特性
- 将来自HTTP/HTTPS URL的文档转换为Markdown格式
- 对数据URI的支持
- 使用可配置密钥的JWT认证
- 健康检查端点
- Docker 支持轻松部署
支持的格式
这台服务器利用MarkItDown的功能,可以转换包括以下在内的各种文件格式:
- PDF文档
- Word文档(.docx)
- PowerPoint 演示文稿(.pptx)
- Excel 电子表格(.xlsx)
- 带OCR功能的图像
- 音频文件(附文字记录)
- 并且MarkItDown支持更多格式
安装
先决条件
- Python 3.12及以上版本
- uv(推荐)或 pip
本地开发
- 克隆仓库:```bash
git clone
cd markitdown-mcp
2. 安装依赖项:```bash
uv sync
- 通过复制并编辑开发环境文件来配置环境变量:```bash
cp .env.development .env
4. 编辑 `.env` 使用您的JWT配置:```env
JWT_PUBLIC_KEY="your-jwt-public-key-pem"
JWT_ISSUER="https://your-issuer.com"
JWT_AUDIENCE="your-audience"
Docker 部署
- 构建Docker镜像:```bash
docker build -t markitdown-mcp .
2. 使用 Docker Compose 运行:```bash
docker-compose up -d
配置
环境变量
变量 · 描述 · 默认值
JWT_PUBLIC_KEY · PEM格式的JWT公钥 · 内置默认密钥
JWT_ISSUER JWT令牌签发者 https://hub.without.systems
JWT_AUDIENCE · JWT令牌受众 · mcp-server
使用方法
作为MCP服务器
将此服务器添加到您的MCP客户端配置中:```json
{
"mcpServers": {
"markitdown": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "/path/to/markitdown-mcp"
}
}
}
### 可用工具
#### `convert_to_markdown`
将资源从URI转换为Markdown格式。
**参数:**
- `uri` (字符串): 指向要转换的文档的HTTP、HTTPS或数据URI
**返回值:**
- 文档的Markdown字符串表示形式
**示例:**```python
# Convert a PDF from a URL
result = convert_to_markdown("https://example.com/document.pdf")
print(result) # Markdown content
HTTP API
服务器还提供了一个HTTP API:
健康检查```
GET /health
返回服务器健康状态。
#### MCP 工具(通过 HTTP)
该服务器支持用于MCP协议通信的流式HTTP传输。
## 发展
### 本地运行```bash
# Activate virtual environment
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Run the server
python server.py
服务器将在 http://localhost:8000。
运行测试```bash
uv run pytest
```
认证
此服务器使用JWT(JSON Web Token)进行身份验证。请确保您的JWT令牌是使用与配置的公钥相对应的私钥签名的,并且包含了正确的签发者(issuer)和受众(audience)声明。
许可证
MIT 许可证 - 详情请参见 LICENSE 文件。
做出贡献
- 为仓库创建分支(或:克隆仓库)
- 创建一个特性分支
- 进行你的更改
- 如适用,请添加测试
- 提交拉取请求
支持
对于问题和疑问,请在仓库中提交一个议题或联系 stefan.weber@without.systems。
