# Obsidian Publish MCP

> Obsidian Publish MCP Server lets your AI read private or public Obsidian markdown notes directly. It indexes your entire digital garden, crawling file paths, understanding link structures, and retrieving raw content from deep within your vault. Use it when you need an agent to know everything in your knowledge base, without you manually opening every single note.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** markdown, vault-indexing, static-site, knowledge-base, note-taking, web-publishing

## Description

You’re connecting Obsidian Publish directly to your AI client. This server treats your entire markdown vault like a fully indexed database. It doesn't just read titles; it crawls the actual internal structure—the links between notes, the metadata attached to files, and the complete raw text of every single note. You use this when you need an agent that knows everything in your knowledge base without having to manually open and paste notes for context.

***

**Mapping Your Whole Vault Structure**

To build a map of your digital garden, you'll first call `list_files` which pulls every published raw file path currently available across the whole Obsidian workspace. You can then use `list_navigation` to see the structural hierarchy of those notes; it visualizes how they’re organized in folders and how they link together conceptually.

**Deep Content Access & Contextual Reading**

When you need the agent to analyze a specific document, you run `get_file`. This action pulls the complete, unedited markdown text of any specified note directly into your workflow. That raw content is crucial; it gives your agent the full context needed for accurate Q&A or summarization.

Understanding relationships between concepts requires more than just reading the text. You call `get_metadata` to pull internal data points from a Markdown page. This extracts things like custom frontmatter properties, applied Obsidian tags (like `#concept`), and creation dates. These structured details let your agent understand how notes relate to each other.

**System Health Check**

To verify that the connection is live and ready for action, you run `site_info`. This pulls global settings information for the entire site deployment. It's a quick ping that confirms connectivity and checks the overall status of the publishing endpoint.

## Tools

### get_file
Pulls the complete, raw markdown text of a specified note into your workflow.

### get_metadata
Extracts internal data points from a Markdown page, like tags or frontmatter properties.

### list_files
Lists every published raw file path currently available across the entire Obsidian workspace.

### list_navigation
Shows the structural hierarchy of your notes, visualizing how they are organized in folders and links.

### site_info
Retrieves global settings information for the entire site deployment to verify connectivity.

## Prompt Examples

**Prompt:** 
```
Check the vault and list all the files currently publicly available.
```

**Response:** 
```
According to the navigation tree, you have 14 distinct markdown entries published. Key documents include 'Index', 'Machine Learning Setup', and 'Project Specs'.
```

**Prompt:** 
```
Read the contents of 'System Requirements 2026.md'.
```

**Response:** 
```
I've pulled the content of 'System Requirements 2026.md'. The document includes heavy focus on horizontal scaling algorithms and Python-centric deployments. Would you like a condensed executive summary?
```

**Prompt:** 
```
Fetch the metadata and tags applied to my 'Inbox' note.
```

**Response:** 
```
The 'Inbox' note has the following metadata: generated on May 5th, tagged with `#todo` and `#ideas`, and links heavily to `Projects.md` and `Archived Content.md`.
```

## Capabilities

### Map entire note structure
Builds contextual trees by listing all published file paths and visualizing how they are linked in the vault.

### Extract raw note content
Streams the complete, unedited markdown text from any specific file into your agent's chat window for analysis.

### Read internal properties and tags
Retrieves metadata like creation dates, custom frontmatter fields, and applied Obsidian tags.

### Identify site configuration
Pings the global settings to confirm connectivity and check the overall deployment status of the publishing endpoint.

## Use Cases

### Finding the original requirements for an old project.
A developer needs to know the initial specs for Project Chimera. Instead of manually searching through folders, they ask their agent. The agent runs `list_files` to locate all 'Chimera' notes, then uses `get_metadata` on them to filter by date and status, finally calling `get_file` to pull the core requirement document for review.

### Summarizing a complex SOP across departments.
The operations team needs to know how three different departmental procedures interact. They ask their agent to map the process. The agent uses `list_navigation` to see the relationship between 'HR Policy' and 'Finance Protocol', then pulls the raw text from both using `get_file` for a single, combined summary.

### Debugging an internal knowledge link.
A writer suspects two concepts are linked incorrectly in the vault. They ask their agent to check the structure. The agent runs `list_files` to confirm both notes exist, then uses `get_metadata` on each to pull the exact frontmatter and tag logic, allowing the user to spot the error instantly.

### Generating a literature review from scattered research notes.
A researcher has hundreds of saved articles. They ask their agent to synthesize the findings. The agent uses `list_files` for scope, then runs `get_file` on all relevant markdown entries in batches, feeding the raw content into a single prompt for synthesis.

## Benefits

- You don't get partial results. Using `get_file` pulls the full raw text body of a note, giving your agent enough context to summarize accurately without needing follow-up prompts.
- Forget manual folder browsing. Running `list_navigation` shows you the structural map of your vault, letting you tell the AI exactly where related concepts live.
- You get more than just file names. The `get_metadata` tool extracts hidden properties and tags—the actual intelligence that connects a note to its project or status.
- The system proves it's working. Running `site_info` provides quick verification that the entire publishing endpoint is connected and ready for deep querying.
- It works in context. By combining `list_files` (to know what exists) with `get_file` (to read what it says), you get a reliable, verifiable knowledge graph.

## How It Works

The bottom line is that your AI client can treat your private markdown vault as if it were connected to a dedicated API endpoint.

1. Subscribe to the server, then provide your Obsidian Publish Site ID (and an access token if the vault is private).
2. Your AI agent uses tools like `list_files` and `list_navigation` to map out the entire contents of your markdown knowledge base.
3. You ask the agent a question. It runs the necessary tool calls (`get_metadata`, `get_file`) to pull the required data, synthesizes it, and gives you an answer.

## Frequently Asked Questions

**How does Obsidian Publish MCP Server handle private vaults?**
It requires you to enter your Site ID and an optional access token for private data. This gives the agent permission to read content that isn't publicly visible.

**Can I use `get_metadata` to find all notes tagged #todo?**
Yes. You run `get_metadata` on specific files, and it pulls out frontmatter properties like tags. This lets your agent search across the whole vault for a common tag.

**What is the difference between `list_files` and `list_navigation`?**
`list_files` gives you every single file path that exists. `list_navigation` shows the structured, linked view—the way a user actually sees it in Obsidian.

**Does Obsidian Publish MCP Server only work for text files?**
No. While markdown is primary, the tools are designed to handle file paths and assets. `get_file` can stream both raw text and binary assets if they are published.

**If I use `list_files`, are there limits to how many file paths can be returned at once?**
No, the tool handles large sets of files by chunking results. The server manages rate limiting automatically so your AI client doesn't hit external API caps when fetching a massive vault structure.

**How does running `site_info` help me verify the Obsidian Publish deployment status?**
It immediately confirms if the connection to your published site is active and correctly configured. This prevents spending time trying to read files that aren't actually live on the web.

**Does `get_file` only pull markdown content, or can it retrieve binary assets too?**
It pulls the complete raw contents, including embedded binary assets like images and PDFs. Your AI client receives these as streamable data payloads for processing.

**Can I use `list_files` to target only files within a specific subdirectory?**
Yes, you can pass path filters when calling the tool. This lets your agent narrow the scope and quickly index documentation in one folder without crawling the entire vault.

**Can the AI accurately recreate the folder structure of my vault?**
Yes. When the model invokes `list_navigation`, it downloads the systematic JSON map of the entire public vault, thereby allowing it to understand the relationships and physical structure of your folders perfectly.

**Does `get_file` automatically render complex Markdown components?**
No rendering is performed on our end. The `get_file` tool returns pure raw Markdown (including frontmatter and obsidian syntax). Fortunately, LLMs (like Claude) are exceptionally adept at reading and reasoning over raw Markdown text structures.

**If my Published site is private and requires a password, does it still work?**
Yes, it works gracefully. If you configured Obsidian Publish with restricted read access, you can manually inject a persistent token into the setup, giving your AI agent the clearance to read securely behind the authentication wall.