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.

✨ Features

Related MCP server: mcp-vision

🚀 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).

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.

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

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.

🛡️ 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.

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.

⚙️ Setup (manual)

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

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

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

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

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

⚙️ Environment variables

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

🔍 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.

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

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

🔐 Safety

🛠️ 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

MIT License · built by @0xnurrabby