md-vision MCP
japlete/md-vision-mcp
Lê markdown com imagens e indexa estrutura de documentação
Ver no GitHubServidor MCP que lê e indexa arquivos markdown com imagens embutidas, permitindo RAG agentico sobre documentação. Oferece duas ferramentas: ler markdown com imagens intercaladas como blocos de conteúdo MCP, e indexar estrutura de heading para descoberta de seções.
Instalação
npx convez-ai japlete/md-vision-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- RAG agentico sobre documentação técnica com imagens
- Indexação dinâmica de estrutura de arquivos markdown
- Leitura targeted de seções específicas com imagens embutidas
Veredito

Ferramenta sólida para agentes que precisam trabalhar com documentação markdown ilustrada. Implementação clara com controles de segurança (allow-path, allow-domain) e integração direta no ecossistema MCP do Claude.
README
A tradução para o português deste README ainda está na fila.
md-vision MCP server
stdio MCP server with two read-only tools for agentic RAG over markdown documentation:
- read_md_with_images — return markdown with referenced images as interleaved image blocks. Avoids an extra tool call for each image to read. Optionally scoped to a specific section or line range.
- index_md — return a compact heading index for a file, URL, or folder of markdown files. Used to dynamically index files for targeted reads.
Typical flow: call index_md to discover headings and structure, then read_md_with_images on the sections you need.
Install: MCP client configuration
Published package: md-vision on npm
In your agent config (.agents/mcp.json or similar), point your MCP host at the server. Example:
{
"mcpServers": {
"md-vision": {
"command": "npx",
"args": [
"md-vision",
"--allow-path",
"/absolute/path/to/docs",
"--allow-domain",
"none"
]
}
}
}
With remote markdown (allow all HTTP(S) hosts, or list specific domains):
{
"mcpServers": {
"md-vision": {
"command": "npx",
"args": [
"md-vision",
"--allow-path",
"/absolute/path/to/docs",
"--allow-domain",
"all"
]
}
}
}
{
"mcpServers": {
"md-vision": {
"command": "npx",
"args": [
"md-vision",
"--allow-path",
"/absolute/path/to/docs",
"--allow-domain",
"raw.githubusercontent.com"
]
}
}
}
The server exits on startup if --allow-path or --allow-domain is omitted.
Restart the MCP host after changing configuration.
Restricting allowed paths and domains
| Flag | Required | Effect |
|---|---|---|
--allow-path <dir> | Yes (at least one) | Local files must resolve under one of the allowed directories (repeatable). |
--allow-domain <host> | Yes (at least one) | Controls HTTP(S) access. Use all to allow any host, none to disable URLs (local files only), or list specific hosts (repeatable; suffix match supported, e.g. example.com allows docs.example.com). |
Equivalent forms: --allow-path=/path, --allow-domain=host.example, --allow-domain=all, --allow-domain=none.
Do not pass a bare * as a separate shell argument — the shell expands it to filenames in the current directory. Use all or --allow-domain=all instead.
Requirements
- Node.js 20+
Tools
read_md_with_images
Read a markdown file and inline referenced images as MCP image content.
| Parameter | Type | Description |
|---|---|---|
uri | string | Local path or http(s):// URL |
section | string, optional | Exact heading to read, e.g. ## Introduction (used when matched; otherwise falls back to line_range) |
line_range | [start, end], optional | Inclusive 1-based document line range (used when section is omitted or not found) |
max_images | integer, optional | Max images to inline (default 10, max 50) |
Returns: MCP content array — alternating text and image blocks (PNG, base64) in document order; frontmatter preserved in the leading text. Before each inlined image, a short text block carries the resolved image URL (omitted for data: URIs and other long references). Images beyond max_images stay as markdown image syntax in text.
URI forms: local filesystem paths and http(s):// URLs. Local paths must fall under a configured --allow-path directory. Relative image paths resolve against the markdown file location or document URL. Images may use markdown  syntax or HTML <img src="..."> tags.
index_md
Index headings for navigation before targeted reads.
| Parameter | Type | Description |
|---|---|---|
uri | string | Markdown file, http(s):// URL, or local folder |
Returns: Markdown string. For each file:
- YAML frontmatter when present.
- A fenced
tsvcode block with columns:heading,line_start,n_images,char_count.
Each file is wrapped in:
<file path="..." lines=X chars=Y>
...
</file>
Folder uri values are scanned recursively for *.md / *.markdown in stable sorted order. Headings inside fenced code blocks are not indexed.
Note on deploying agents with this MCP server
stdio MCP servers run as subprocesses of the agent runtime that invokes them. There are two deployment patterns commonly used:
- Agent-in-sandbox (runtime shares the agent’s filesystem): the server can read docs in-place; scope
--allow-pathto the documentation tree you intend to expose. - Sandbox-as-tool (runtime filesystem differs from the tool sandbox): the MCP process usually runs in the runtime environment, so markdown must be copied or synced where the server can read it.
Benchmark (WIP)
See benchmark/ for the MMLongBench-Doc A/B harness comparing
filesystem-only agentic RAG against the same agent with md-vision MCP tools.