Obsidian MCP (pgvector + Ollama, self-hosted)

read_file

Read any file from an Obsidian vault, including PDFs, images, and data files, with auto text, inline image, or base64 encoding.

Instructions

Read any file in the vault — including non-markdown (PDFs, images, skill HTML/JS, data files). Peer to read_note, which stays markdown-only.

This is pure byte transport: the server does NOT extract or parse PDFs and cannot interpret binary bytes. Non-text/non-image files come back as an opaque base64 string intended for a client-side skill to decode — not as something the model can read directly.

Encoding:

"auto" (default): text-like files (HTML, JSON, CSV, source, …) return as readable text; images (PNG/JPEG/GIF/WebP) return as an inline image block that renders in-client; everything else returns as a labeled base64 string.
"text": force a UTF-8 text decode; errors if the file is not valid UTF-8.
"base64": force a raw-bytes base64 string regardless of type.

Files larger than MAX_FILE_READ_BYTES (default 10 MB) are refused with a size report. Base64 reads pass through the model context and inflate ~33%, so they are token-heavy — check a file's size with list_files before reading large binaries. Any path with a component starting with . is rejected — dot-directories (.obsidian, .git, .trash, …) and dot-files alike — as is path traversal.

Text results are additionally capped to a context-safe size: the cap bounds the returned window, and a truncated read appends a short notice carrying the offset to continue from. Base64 and image results are not windowed.

The base64 header and hash_only=True return the whole raw file's content_hash (sha256:<64 lowercase hex>), which write/delete tools accept as expected_hash. Their path is a quoted JSON string. Text stays deliberately unenveloped. Use base64 for byte-exact frontmatter bytes; read_note.frontmatter_yaml has normalized line endings.

Encoding is validated first, then hash_only/window compatibility, then ranges. hash_only refuses offset != 0 or any non-None limit; explicitly passing offset=0 is fine. A valid encoding has no effect in this mode.

Args: path: Vault-relative path to the file (e.g. "Reference Docs/spec.pdf"). hash_only: Return only path, byte count, MIME and hash, with no content. encoding: One of "auto" (default), "text", or "base64". offset: Character offset to start a text read from (default 0). Use the value the truncation notice reports to continue. limit: Maximum characters to return for a text read. Only lowers the server cap; it cannot raise it.

Input Schema

TableJSON Schema

Name	Required	Default
`path`	Yes
`limit`	No
`offset`	No
`encoding`	No	auto
`hash_only`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.2Sep 24, 2026
- addedInput schema / additionalProperties
```
Added value: +false
```

Changed1 schema field changedv0.8.1Sep 16, 2026

addedInput schema / properties / hash_only

Added value: +{
+  "default": false,
+  "title": "Hash Only",
+  "type": "boolean"
+}

Changed2 schema fields changedv0.7.0Aug 19, 2026

addedInput schema / properties / limit

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Limit"
+}

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "title": "Offset",
+  "type": "integer"
+}

Addedv0.4.0Jun 26, 2026

TDQS

A5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so thoroughly. It discloses that the server does not parse PDFs or interpret binaries, explains encoding behaviors (auto/text/base64) and their return formats, size caps (10 MB refusal, windowing), security restrictions (dot-path rejection, traversal rejection), the truncation notice with offset continuation, validation order, and hash-only behavior. It even notes the ~33% base64 size inflation. This goes well beyond a basic mutation description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place. It is front-loaded with the core purpose and sibling contrast, then organized into clearly labeled sections (encoding, size limits, path restrictions, windowing, hash, validation order). There is no filler; the structure makes the dense information easily scannable for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, no schema coverage, no annotations, no output schema), the description covers every aspect an agent needs to call it correctly: return types for each encoding, size caps, security, windowing, hash behavior, and validation precedence. It even specifies the hash format and that text results are unenveloped. Nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must fully explain parameters, and it does. Each parameter is defined: `path` (vault-relative), `hash_only` (metadata only), `encoding` (with detailed auto/text/base64 semantics), `offset` (character offset, use truncation notice value), and `limit` (only lowers cap). It also explains interactions (e.g., `hash_only` refuses non-zero offset or non-None limit, valid encoding has no effect in hash_only) and gives examples of path format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb-resource pair: 'Read any file in the vault' and explicitly contrasts itself with `read_note` ('which stays markdown-only'), instantly distinguishing its scope from a sibling. The inclusion of non-markdown types (PDFs, images, skill HTML/JS, data files) further sharpens the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: it is the tool for any non-markdown file, while `read_note` is the markdown-only alternative. It also advises checking file size with `list_files` before reading large binaries, warns about token inflation with base64, and explains when to use `hash_only` for byte-exact frontmatter bytes. These conditions and alternatives are unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_file

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools