# ocular [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/xyun1996/ocular  
**GitHub Stars:** 0  
**npm Downloads (last month):** 96  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ocular

## Description
Vision tools for coding agents: screenshots, OCR, UI diffs, errors, tables, and charts.

## Tools
Capabilities this server exposes over MCP:

- **analyze_image** — Analyze a general image and return structured JSON for a coding agent.
- **extract_text_from_image** — Extract OCR text from screenshots, documents, tables, terminal output, or code images.
- **analyze_ui_screenshot** — Analyze a webpage, app, UI, or design mockup screenshot for frontend implementation work.
- **diagnose_error_screenshot** — Analyze error, terminal, console, browser, or build failure screenshots.
- **compare_ui_screenshots** — Compare two UI screenshots and return implementation-useful visual differences.
- **extract_table_from_image** — Extract visible table data from an image as structured JSON, Markdown, or CSV-oriented output.
- **analyze_chart_image** — Analyze a chart image and return labels, trends, approximate values, and limitations.
- **create_upload_session** — Returns upload instructions for the binary side channel (use this to analyze LOCAL image files without base64 corruption). Before uploading, verify the local file exists and is non-empty with Bash (e.g. `ls -la <path>` or `test -f <path> && stat -c %s <path>`). Then PUT the raw bytes to the returned upload_url with curl --data-binary (NOT base64); the response gives a file_id to pass to any vision tool. Stateless -- call once to learn the endpoint.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ocular": {
    "command": "npx",
    "args": ["-y","ocular-mcp"],
    "env": {
      "OCULAR_BASE_URL": "",
      "OCULAR_API_KEY": "",
      "OCULAR_MODEL": ""
    }
  }
}
```

**Requires environment variables:** `OCULAR_BASE_URL`, `OCULAR_API_KEY`, `OCULAR_MODEL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What ocular MCP server does

The ocular MCP server connects text-first coding agents with OpenAI-compatible multimodal vision models. It converts visual inputs into structured results that an agent can use alongside repository and project context. Supported inputs include screenshots, interface mockups, terminal or browser error captures, documents, tables, and charts.

The server exposes eight MCP tools. General image analysis handles broad inspection, while specialized tools target OCR, UI review, error diagnosis, screenshot comparison, table extraction, chart interpretation, and remote upload setup. Outputs are intended for agent workflows rather than prose-only image descriptions.

## How it works

A client sends an MCP tool request to ocular with either a `file_id` or, where supported for local use, inline base64 image data. The server packages the image and request for an OpenAI-compatible vision endpoint, then returns the model result as structured JSON.

For remote operation, the recommended sequence is to upload raw image bytes with an HTTP `PUT /upload` request. The upload produces a content-addressed `file_id`, which the client supplies to a later vision-tool call. This keeps large image payloads out of the MCP request itself. Uploads can be deduplicated, and result caching is available for repeated workflows.

The server supports stdio for locally launched MCP clients and HTTP transport for hosted or private deployments. HTTP mode can use an authentication token and configurable host, port, and path settings.

## Setup and configuration

Install the published `ocular-mcp` package globally with npm, run it through `npx`, or build the repository from source. The project requires Node.js 20 or newer. A normal local launch uses the `ocular` command and communicates over standard input and output.

The ocular MCP server requires three provider settings: `OCULAR_BASE_URL` for the OpenAI-compatible API endpoint, `OCULAR_API_KEY` for authentication, and `OCULAR_MODEL` for the vision-capable model name. Optional settings control provider headers, temperature, token limits, timeouts, image-size limits, caching, upload storage, and the public upload URL.

For HTTP deployments, set `MCP_TRANSPORT=http` and configure the host, port, path, and authentication variables as needed. Remote clients also need access to the upload endpoint when using the binary upload flow.

## Tools and capabilities

- `analyze_image` performs general structured image inspection.
- `extract_text_from_image` extracts text while considering reading order and layout.
- `analyze_ui_screenshot` reviews hierarchy, spacing, typography, and accessibility concerns.
- `diagnose_error_screenshot` extracts and analyzes terminal, browser, or build errors.
- `compare_ui_screenshots` compares a reference image with an implementation image.
- `extract_table_from_image` turns visible table content into structured data.
- `analyze_chart_image` examines labels, values, trends, and uncertainty.
- `create_upload_session` provides upload details for remote clients.

## Limitations and notes

The server depends on an OpenAI-compatible multimodal endpoint and a model that supports vision. Compatibility is specific to the endpoint and model combination; the project documents smoke-tested configurations rather than treating API compatibility as automatic.

The project is described as early-stage and actively evolving. Vision results depend on the selected provider and model, and the included benchmark measures execution, JSON structure, and timing rather than broad model quality. Avoid placing long-lived provider keys directly in shared shell history; use the MCP client’s environment or secret-management features when available.

_Full upstream README: https://allmcps.com/mcp/ocular/readme_