# GLM OCR MCP Server
MCP server for extracting text from images and PDFs using ZhipuAI GLM-OCR.
## Usage
```json
{
"mcpServers": {
"glm-ocr": {
"command": "uvx",
"args": ["glm-ocr-mcp"],
"env": {
"ZHIPU_API_KEY": "your_api_key_here",
"ZHIPU_OCR_API_URL": "https://open.bigmodel.cn/api/paas/v4/layout_parsing"
}
}
}
}
```
### Using with Claude Code
```bash
claude mcp add --scope user glm-ocr \
--env ZHIPU_API_KEY=your_api_key_here \
--env ZHIPU_OCR_API_URL=https://open.bigmodel.cn/api/paas/v4/layout_parsing \
-- uvx glm-ocr-mcp
```
### Using with Codex
Add MCP server with command:
```bash
codex mcp add glm-ocr \
--env ZHIPU_API_KEY=your_api_key_here \
--env ZHIPU_OCR_API_URL=https://open.bigmodel.cn/api/paas/v4/layout_parsing \
-- uvx glm-ocr-mcp
```
### Tools
The server provides one tool:
- **extract_text**: Extract from local file or URL (`png`, `jpg/jpeg`, `pdf`)
- default returns Markdown text
- set `return_json=true` to return structured JSON without `md_results` (contains page parsing details like `bbox_2d`, `content`, `label`, etc.)
Parameters:
- **file_path**: Local file path or URL for `png`, `jpg/jpeg`, or `pdf`
- **base64_data**: Optional data URL/base64 payload (use when `file_path` is unavailable)
- **start_page_id**: Optional PDF start page (1-based, only effective for PDF)
- **end_page_id**: Optional PDF end page (1-based, only effective for PDF)
- **return_json**: Optional boolean, default `false`. `true` returns JSON; `false` returns Markdown.
### Examples
```python
# Extract text from local image
extract_text(file_path="./screenshot.png")
# Extract text from local PDF
extract_text(file_path="./document.pdf")
# Extract text from URL image
extract_text(file_path="https://example.com/test.jpg")
# Use base64/data URL
extract_text(base64_data="data:image/png;base64,iVBORw0KGgo...")
# Extract structured layout JSON
extract_text(file_path="https://example.com/test.png", return_json=True)
```
## Development
```bash
# Create virtual environment
uv venv
source .venv/bin/activate
# Sync dependencies and install current project
uv sync
# Run server for testing
python -m glm_ocr_mcp.server
```
Windows PowerShell activation:
```powershell
.venv\Scripts\Activate.ps1
```
## Project Structure
```
glm-ocr-mcp/
├── pyproject.toml # Project configuration
├── README.md # Documentation
├── .env.example # Environment variable template
├── src/
│ └── glm_ocr_mcp/
│ ├── __init__.py
│ ├── __main__.py # Entry point
│ ├── ocr.py # OCR client
│ └── server.py # MCP server
```
