<div align="center">

<img src="https://raw.githubusercontent.com/0xnurrabby/mcp-omni-context/master/assets/logo.svg" alt="mcp-omni-context" width="110">

mcp-omni-context

Give any AI chat real vision.

Read images, files, and zip archives in any language, for any AI model. Works everywhere MCP works. No Python, no servers. OCR runs locally by default.

</div>

---

✨ Features

	Feature	What it does
🖼️	Screenshot reading	Reads any screenshot, at any angle, in any language
🤖	Optional AI vision	Add a key in .env → images read by GPT-4o-mini or Gemini (≈ $0.001/image)
🔁	Auto fallback	If the AI API fails (or no key set), it silently uses local OCR instead
🧲	Auto-detection	Pasted/dropped screenshots are found automatically in the temp/clipboard folders — no copying files anywhere
📄	File & log reader	Code files and error traces, line by line
📦	Zip explorer	Visual file tree plus every code file inside
🌍	Any language	English, Bengali, Hindi, Arabic, Chinese and more
🪄	Zero setup for users	One command installs it for any AI tool
🔒	Privacy first	With no API key, OCR runs 100% locally

---

🚀 Download & Run

Everything lives behind two tools: read_context_data and find_images.

Step 1 · Check you have Node.js (20.17+)

node -v

Step 2 · No command? Just ask your AI assistant

"please setup mcp-omni-context"

Step 3 · Or run it yourself

npx -y mcp-omni-context setup

Then restart your AI tool. Done. That's the whole setup.

It configures opencode, Codex, Claude Desktop, Cursor, Windsurf, Cline, Roo, and VS Code, backs up your existing configs, and creates an uploads folder at ~/.mcp-omni-context/uploads.

💡 Pasting a screenshot? Send it straight to your assistant. If the path is not obvious, the assistant calls find_images to locate the freshest images in your temp, clipboard, Downloads, Desktop, Pictures, and uploads folders. You never have to save or copy a file manually.

---

⚙️ Optional: better accuracy with AI vision (~$0.001 / image)

By default every image is read by local OCR (tesseract.js) — free and private.

For noticeably better UI/error-screen reading, add one API key to a file named .env in your project folder (the same folder you run the AI tool from).

<details> <summary><b>Option A — OpenAI (recommended)</b></summary>

1. Create an API key at https://platform.openai.com/api-keys
2. Create a .env file in your project and paste:

OPENAI_API_KEY=sk-your-key-here

That's it. Images are resized to max 1024px with sharp, compressed to JPEG, and sent with detail: "low" — keeping the cost at roughly $0.001 per image with GPT-4o-mini.

</details>

<details> <summary><b>Option B — Google Gemini</b></summary>

1. Get a free key at https://aistudio.google.com/app/apikey
2. Create a .env file in your project and paste:

GEMINI_API_KEY=your-gemini-key

</details>

<details> <summary><b>Where else can the key live?</b></summary>

Keys are read from (first match wins):

1. Your environment variables (e.g. set OPENAI_API_KEY=... on Windows, export OPENAI_API_KEY=... on macOS/Linux), or
2. a .env file in the current project folder, or
3. a .env file at ~/.mcp-omni-context/.env.

Existing environment variables are always respected over .env values. New keys take effect immediately; you only need to restart the AI tool. </details>

🛡️ Fail-safe: if the vision API is down, returns an error, or the key is missing, the tool automatically falls back to local OCR — you always get a result, never a crash.

---

🛠️ Tools

read_context_data

Reads images, files, logs, and zip archives and returns a strictly-ordered, LLM-ready text dump. Accepts:

• a path: {"items": ["C:/Users/you/Desktop/shot.png"]}
• many paths in one call: {"items": ["a.png", "b.png", "error.log", "src/"]}
• a bare file name (auto-resolved from the system temp/clipboard folders)
• an in-memory buffer: {"items": [{"name": "a.png", "base64": "..."}]}

Each image is processed sequentially and wrapped in a clear delimiter:

--- [Image Index 1] Visual Analysis ---
[Source: C:/Users/you/Desktop/shot.png]
[Vision AI · gpt-4o-mini · detail=low · jpeg 181.2 KB · raster 2560x1440]
<the analysis / transcribed text>

--- [Image Index 2] Visual Analysis ---
...

find_images

Locates the freshest screenshots across your temp, clipboard, Downloads, Desktop, Pictures, Telegram Desktop, and uploads folders — newest first.

find_images                 → 10 newest images
find_images maxResults: 50  → up to 50
find_images query: "bug"    → only files whose name contains "bug"
find_images sinceMinutes: 10→ only images from the last 10 minutes

---

📦 Updating

Updates are automatic. Every client runs this via npx -y, so the newest version loads on the next start. Zero clicks, zero reinstall.

<details> <summary><b>Want to update right now?</b></summary>

Just tell your assistant:

"update mcp-omni-context"

Or run the one-command update yourself:

npx -y mcp-omni-context update

It fetches the latest version and refreshes your configs and rules.

</details>

---

⚙️ Setup (manual)

The installer writes all of this for you. For the curious, here is how each client is configured.

<details> <summary><b>opencode</b> · <code>opencode.json</code></summary>

{
  "mcp": {
    "omni-context": {
      "type": "local",
      "command": ["npx", "-y", "mcp-omni-context"],
      "enabled": true
    }
  }
}

</details>

<details> <summary><b>Claude Desktop</b> · <code>claude_desktop_config.json</code></summary>

{
  "mcpServers": {
    "omni-context": {
      "command": "npx",
      "args": ["-y", "mcp-omni-context"]
    }
  }
}

</details>

<details> <summary><b>Cline / Cursor / Windsurf / Roo</b> · <code>mcpServers</code></summary>

{
  "mcpServers": {
    "omni-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-omni-context"]
    }
  }
}

</details>

<details> <summary><b>Codex CLI</b> · <code>~/.codex/config.toml</code></summary>

[mcp_servers.omni-context]
command = "npx"
args = ["-y", "mcp-omni-context"]

</details>

---

⚙️ Environment variables

All of these can go in a .env file or your real environment.

Variable	Default	What it does
OPENAI_API_KEY	—	Enables GPT-4o-mini vision (resized to 1024px, detail: "low", ~$0.001/img)
OPENAI_MODEL	gpt-4o-mini	Override the OpenAI vision model
OPENAI_BASE_URL	https://api.openai.com/v1	Use any OpenAI-compatible endpoint
GEMINI_API_KEY	—	Enables Google Gemini vision instead
GEMINI_MODEL	gemini-2.0-flash	Override the Gemini model
MCP_OMNI_VISION	auto	auto · openai · gemini · tesseract (force local OCR)
MCP_OMNI_ENV_FILE	—	Path to a specific .env file to read
MCP_OMNI_VERBOSE	off	1 to log OCR/vision progress to stderr
MCP_OMNI_PSM	3	tesseract page-segmentation mode (0–13)

---

🔍 How it reads

Your assistant reads context through read_context_data. It accepts any number of images, files, logs, or zip archives in order, and returns a strictly ordered, LLM-ready text dump.

<details> <summary><b>Reading in any language</b></summary>

OCR defaults to English + Bengali. For other languages, just tell your assistant the language (Hindi, Arabic, Chinese, Spanish, French, German, Russian, Japanese, Korean, Urdu, and many more). The language data downloads itself, or pre-download once:

npx -y mcp-omni-context --warmup eng,ben,hin,spa,fra,urd

</details>

<details> <summary><b>Project structure</b></summary>

src/
└── index.ts          # the entire server (tool + vision + zip tree + setup + update)
dist/                 # compiled output (published)
README.md
package.json

</details>

---

🔐 Safety

	Guard	What it means
🚫	Sensitive files	.env, id_rsa, *.pem, secrets.*, tokens are skipped
📦	Binary & heavy	ignore node_modules, media, and oversized blobs
🛡️	Zip-slip	blocks .. and absolute paths inside archives
🧼	Auto-cleanup	temp files are purged after every run
💸	Low cost	AI vision resizes to 1024px and sends detail: "low" (~$0.001/img)

---

🛠️ CLI reference

mcp-omni-context                      start the MCP server (stdio)
mcp-omni-context setup                configure all supported clients
mcp-omni-context update               fetch latest + refresh configs and rules
mcp-omni-context --check-update       check the latest published version
mcp-omni-context --warmup [langs]     pre-download OCR language data
mcp-omni-context --selftest           check OCR works on your machine
mcp-omni-context --help               show help
mcp-omni-context --version            show version

---

<div align="center">

MIT License · built by @0xnurrabby

</div>