Metadata-Version: 2.5
Name: mcp-glm-ocr
Version: 0.1.0
Summary: Free OCR & vision MCP server for any AI client, powered by GLM-4.6V-Flash (z.ai)
Project-URL: Homepage, https://github.com/iwanro/mcp-ocr-glm
Project-URL: Repository, https://github.com/iwanro/mcp-ocr-glm
Project-URL: Issues, https://github.com/iwanro/mcp-ocr-glm/issues
License: MIT
License-File: LICENSE
Keywords: free,glm,image,mcp,model-context-protocol,ocr,vision,z.ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<3,>=2.0.0
Description-Content-Type: text/markdown

# mcp-glm-ocr

```text
                                  _                                 
 _ __ ___   ___ _ __         __ _| |_ __ ___         ___   ___ _ __ 
| '_ ` _ \ / __| '_ \ _____ / _` | | '_ ` _ \ _____ / _ \ / __| '__|
| | | | | | (__| |_) |_____| (_| | | | | | | |_____| (_) | (__| |   
|_| |_| |_|\___| .__/       \__, |_|_| |_| |_|      \___/ \___|_|   
               |_|          |___/                                   
```

**Free OCR & vision for any AI coding client, powered by GLM-4.6V-Flash.**

`mcp-glm-ocr` is an [MCP](https://modelcontextprotocol.io) server that gives
OCR and image-understanding capabilities to AI clients that cannot process
images themselves (Claude Code, Claude Desktop, Cursor, Cline, OpenCode, and
any other MCP-compatible client).

Under the hood it sends the image to [GLM-4.6V-Flash](https://docs.z.ai/guides/vlm/glm-4.6v),
z.ai's vision-language model, which is **completely free** (input and output).
The model reads the image and returns text, so your text-only client gets full
vision capabilities at zero cost.

> Why this exists: z.ai's official vision MCP server is exclusive to paid
> GLM Coding Plan subscribers. This one works with a plain free z.ai account.

## Tools

| Tool | Description |
| --- | --- |
| `ocr_image(image)` | Extract all text from an image (screenshots, photos, receipts, document pages). |
| `describe_image(image)` | Detailed description of what an image shows. |
| `analyze_image(image, prompt)` | Answer a custom question about an image (charts, tables, diagrams, UI screenshots, math...). |

All tools accept:

- a **local file path** (absolute, or relative to the client's working directory), e.g. `demo.png`
- an **http(s) URL**, e.g. `https://example.com/photo.jpg`
- a **`file://` URL** or a **`data:` URL**

## Requirements

- Python 3.10+ (or just [`uv`](https://docs.astral.sh/uv/))
- A free z.ai API key

### Get a free API key

1. Go to <https://z.ai/model-api> and create an account (or log in).
2. Create an API key at <https://z.ai/manage-apikey/apikey-list>.
3. GLM-4.6V-Flash costs nothing to use.

## Installation & configuration

### 1. Claude Code

```bash
claude mcp add glm-ocr --env ZAI_API_KEY=your_key -- uvx mcp-glm-ocr
```

Then in any conversation:

```
> what does demo.png say?
> read the text from receipt.jpg
> describe this image: ~/Pictures/screenshot.png
> analyze this chart: chart.png — what is the trend?
```

### 2. Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "glm-ocr": {
      "command": "uvx",
      "args": ["mcp-glm-ocr"],
      "env": { "ZAI_API_KEY": "your_key" }
    }
  }
}
```

### 3. Cursor

In `.cursor/mcp.json` at the root of your project:

```json
{
  "mcpServers": {
    "glm-ocr": {
      "command": "uvx",
      "args": ["mcp-glm-ocr"],
      "env": { "ZAI_API_KEY": "your_key" }
    }
  }
}
```

### 4. Cline (VS Code)

In Cline settings → MCP servers:

```json
{
  "mcpServers": {
    "glm-ocr": {
      "command": "uvx",
      "args": ["mcp-glm-ocr"],
      "env": { "ZAI_API_KEY": "your_key" }
    }
  }
}
```

### 5. OpenCode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "glm-ocr": {
      "type": "local",
      "command": ["uvx", "mcp-glm-ocr"],
      "environment": { "ZAI_API_KEY": "your_key" }
    }
  }
}
```

### Without `uv` (pip / Docker)

```bash
pip install mcp-glm-ocr
mcp-glm-ocr          # requires ZAI_API_KEY env var
```

```bash
docker run --rm -i -e ZAI_API_KEY=your_key mcp-glm-ocr
```

## Environment variables

| Variable | Default | Description |
| --- | --- | --- |
| `ZAI_API_KEY` | — | **Required.** Your z.ai API key. `Z_AI_API_KEY` is also accepted. |
| `ZAI_MODEL` | `glm-4.6v-flash` | Model to use. Switch to `glm-4.6v` for higher quality (paid), or `glm-ocr` for a dedicated cheap OCR model. |
| `ZAI_BASE_URL` | `https://api.z.ai/api/paas/v4/` | API base URL. Lets you point at a proxy or self-hosted gateway. |
| `ZAI_TIMEOUT` | `120` | HTTP timeout in seconds. |
| `ZAI_MAX_TOKENS` | `4096` | Max output tokens per call. |
| `ZAI_MAX_IMAGE_MB` | `15` | Max local image size in MB (larger files are rejected). |

## Development

```bash
uv sync --all-groups        # install deps + dev deps
uv run pytest -q            # unit tests (no network, no API key)
uv run python scripts/smoke_stdio.py   # boots the real stdio MCP server, lists tools
uv run mcp-glm-ocr          # run the server locally (needs ZAI_API_KEY)
uv run mcp-glm-ocr --version
uv run python scripts/banner.py   # print the banner in color (terminal)

# real end-to-end call against the z.ai API (needs a real key).
# Omitting the image uses the bundled test fixture (tests/fixtures/test_image.png):
ZAI_API_KEY=your_key uv run python scripts/live_test.py
ZAI_API_KEY=your_key uv run python scripts/live_test.py path/to/your/image.png
```

## How it works

1. The client model calls `ocr_image` / `describe_image` / `analyze_image`.
2. The server resolves the image (local file → base64 `data:` URL, or passthrough for URLs).
3. It calls `POST /chat/completions` on the z.ai OpenAI-compatible API with model `glm-4.6v-flash`.
4. The text answer is returned to the client model.

## Limitations

- Images only (no video). Video is out of scope for this free model.
- Free tier has rate limits set by z.ai; check the [rate limits docs](https://docs.z.ai/api-reference/rate-limit.md).
- Very large images are rejected by default (`ZAI_MAX_IMAGE_MB=15`).

## Releasing (maintainer)

Option A: tag a version and let GitHub Actions build and publish automatically:

```bash
git tag v0.1.0 && git push --tags
```

Prerequisite: create a PyPI API token at <https://pypi.org/manage/account/token/>
and store it as the `PYPI` secret in the GitHub repo settings.

Option B: publish manually:

```bash
uv build                          # build sdist + wheel
uv publish                        # push to PyPI (requires a PyPI token)
```

After publishing, users install with `uvx mcp-glm-ocr` or `pip install mcp-glm-ocr`.
Remember to bump `version` in `pyproject.toml` and `src/mcp_glm_ocr/__init__.py`
for each release.

## License

MIT
