read_md_with_images — return markdown (optionally scoped) with referenced images as MCP image blocks.
index_md — build a compact heading index for a file, URL, or folder of markdown files.

Typical flow: call index_md to discover headings and structure, then read_md_with_images on the sections you need.

Requirements

Node.js 20+

Install

Published package: md-vision on npm

npx md-vision --allow-path /path/to/docs --allow-domain none

Or install globally:

npm install -g md-vision
md-vision --allow-path /path/to/docs --allow-domain none

From a clone of this repo:

npm install
npm run build

MCP client configuration

In your agent config (.agents/mcp.json or similar), point your MCP host at the server. Example using npx:

{
  "mcpServers": {
    "md-vision": {
      "command": "npx",
      "args": [
        "md-vision",
        "--allow-path",
        "/absolute/path/to/docs",
        "--allow-domain",
        "none"
      ]
    }
  }
}

Local development (absolute path to built dist/server.js):

{
  "mcpServers": {
    "md-vision": {
      "command": "node",
      "args": [
        "/absolute/path/to/md-vision-mcp/dist/server.js",
        "--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.

Development

npm run dev          # rebuild on change
npm test             # vitest
npm run build        # dist/server.js
npm start            # run built server (stdio)

# Interactive smoke test
npx @modelcontextprotocol/inspector node dist/server.js --allow-path . --allow-domain none

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 tsv code 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.

Agent-in-sandbox (runtime shares the agent’s filesystem): the server can read docs in-place; scope --allow-path to 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.