mcp-omni-context

Give any AI chat real vision.

Send it images, files, or zip archives and it reads them for you, in any language, in every AI tool that supports MCP. No API keys required, nothing to host, no Python.

🎯 All you need: 2 steps, done

STEP 1 · Open your AI assistant (opencode, Claude, Cursor, Codex...) and paste this exact line:

please setup mcp-omni-context

STEP 2 · Restart your assistant.

That's it. Now send it a screenshot and it will read it. Free, local, no key.

Don't use a terminal? You already finished - steps 1 and 2 are everything.

🤖 Want to run the command yourself instead?

If you have Node.js installed, open a terminal and run:

npx -y mcp-omni-context setup

then restart your assistant. Same result.

Where do pasted files go? Setup creates its own folder named OMNI-Vision-DD (in ~/.mcp-omni-context/). The first time you send an image/file/zip the assistant politely asks permission, and once you agree it simply saves what you give it into that folder and reads it from there. No path to type, no file finding - just paste and send. Giving a file path works too.

⭐ Optional: make the vision smarter (AI vision)

Without anything extra, images are read with free local OCR (it extracts the text). If you want a pixel-perfect description of the image instead - every element, exact text, colors, positions, shadows - add one API key. Any user can do it:

Easiest · Just paste your key to your assistant, replacing the text after =:

set this API key for me: GEMINI_API_KEY = AIzayour-key-goes-here

or, if you use OpenAI instead:

set this API key for me: OPENAI_API_KEY = sk-your-key-goes-here

Your assistant does the rest and tells you when it's done.

Or run it yourself · In a terminal:

npx -y mcp-omni-context keys

pick 1 (Gemini) or 2 (OpenAI), paste the key, confirm with y, done.

• To see which keys are stored: npx -y mcp-omni-context keys show
• To remove a key: npx -y mcp-omni-context keys remove gemini (or openai)

Your key stays on your computer (~/.mcp-omni-context/.env) and inside your assistant's config. It is never sent anywhere except to the vision provider you chose. Remove it anytime with the same keys command (and it cleans the config too).

🖥️ How it is configured in every app

You never need to touch these files - setup writes them for you. But here is the exact block each app gets, so you know what to expect. Each app has its own config format, so they look a bit different - that is normal and correct.

The optional env block (API key for AI vision) appears the moment you add a key and disappears when you remove it. Setup does all of this automatically.

opencode - file ~/.config/opencode/opencode.jsonc

opencode uses its own mcp format (not mcpServers):

{
  "mcp": {
    "omni-context": {
      "type": "local",
      "command": ["npx", "-y", "mcp-omni-context"],
      "enabled": true,
      "timeout": 60000,
      "env": { "GEMINI_API_KEY": "your key here" }
    }
  }
}

Codex CLI - file ~/.codex/config.toml

Codex uses TOML:

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

(Codex config holds no env block; the server reads a stored key from ~/.mcp-omni-context/.env on its own.)

Claude Desktop - file claude_desktop_config.json

{
  "mcpServers": {
    "omni-context": {
      "command": "npx",
      "args": ["-y", "mcp-omni-context"],
      "env": { "GEMINI_API_KEY": "your key here" }
    }
  }
}

Claude Code / Cline / Roo - project file .mcp.json

{
  "mcpServers": {
    "omni-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-omni-context"],
      "env": { "GEMINI_API_KEY": "your key here" }
    }
  }
}

Cursor - file ~/.cursor/mcp.json

{
  "mcpServers": {
    "omni-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-omni-context"],
      "env": { "GEMINI_API_KEY": "your key here" }
    }
  }
}

Windsurf - file ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "omni-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-omni-context"],
      "env": { "GEMINI_API_KEY": "your key here" }
    }
  }
}

VS Code - file .vscode/mcp.json

VS Code uses a servers key instead of mcpServers:

{
  "servers": {
    "omni-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-omni-context"],
      "env": { "GEMINI_API_KEY": "your key here" }
    }
  }
}

✨ Features

| | Feature | What it does | |---|---|---| | 🖼️ | Image reading | Free local OCR by default, no key, nothing leaves your machine | | 🤖 | AI Vision | Optional pixel-perfect JSON layout (Gemini or OpenAI) | | 🔎 | Auto-find images | Locates a pasted image automatically - never left unread | | 📄 | 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 line to your assistant and it is installed | | 🔒 | Privacy first | OCR runs locally; nothing leaves your machine |

📦 Updating

Updates are automatic: every assistant runs this via npx -y, so the newest version loads on the next restart. Zero clicks.

To force it now, paste to your assistant:

update mcp-omni-context

or run in a terminal:

npx -y mcp-omni-context update

🔍 How it reads

Your assistant reads context through one tool (read_context_data). Give it any number of images, files, logs, or zip archives; you get back a strictly ordered, LLM-ready text dump. If a pasted image has no file path, the assistant first finds it automatically (find_image scans the OMNI-Vision-DD folder, Desktop, Downloads, and Pictures) and reads it - it never tells you it cannot see an image. Patterns it understands:

OCR defaults to English + Bengali. For another language (Hindi, Arabic, Spanish, French, German, Chinese, Urdu...) just tell your assistant the language - the data downloads itself. Or pre-download it once:

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

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

👁️ Vision engine (how it picks)

| Step | Condition | What you get | |---|---|---| | 1 | GEMINI_API_KEY set | gemini-1.5-flash -> pixel-perfect JSON layout | | 2 | only OPENAI_API_KEY set | gpt-4o-mini -> same JSON layout | | 3 | no key, or the API call fails | free local OCR (never breaks) |

So an image is never left unread - even offline or without any key. You can also force one engine with MCP_OMNI_VISION=gemini|openai|off.

🛠️ Command 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 keys                 add/remove/change AI vision keys (menu)
mcp-omni-context keys set <gemini|openai> <KEY>
mcp-omni-context keys remove <gemini|openai>
mcp-omni-context keys show
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

🔐 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 |

MIT License · built by @0xnurrabby