Obsidian Pdf Evidence

🚀 Obsidian PDF Evidence

An Obsidian plugin that exposes PDF content and vault context to AI agents via MCP (Model Context Protocol).

한국어 README

✨ Features

• PDF Text Extraction: Extract and cache text from PDFs open in Obsidian.
• Fuzzy Search with PDF++ Citations: Find text snippets in PDFs and generate clickable PDF++ citation links.
• Vault Access: Read/write markdown files, search vault content, manage tags.
• Dataview Integration: Run Dataview queries through the API.
• AI Answers Panel: Display AI responses with clickable internal links in Obsidian's sidebar.

📦 Installation

From Source

1. Clone and build the plugin:

git clone https://github.com/your-repo/obsidian-pdf-evidence
cd obsidian-pdf-evidence
npm install
npm run build

2. Create the plugin directory in your Obsidian vault:

mkdir -p {your-vault}/.obsidian/plugins/obsidian-pdf-evidence

3. Copy all contents from dist/ to the plugin directory:

cp -r dist/* {your-vault}/.obsidian/plugins/obsidian-pdf-evidence/

The final structure should look like:

{your-vault}/.obsidian/plugins/obsidian-pdf-evidence/
├── main.js
├── manifest.json
├── styles.css
└── bridge/
    └── bridge.mjs

4. Enable the plugin in Obsidian:
   • Open Obsidian Settings → Community plugins.
   • Turn off "Restricted mode" if prompted.
   • Click "Reload plugins" or restart Obsidian.
   • Find "Obsidian PDF Evidence" and toggle it on.

Plugin Settings

📚 Documentation

MCP Configuration

The plugin provides a local HTTP server that MCP bridge clients can connect to. You can copy the configuration directly from the plugin settings using the "Copy MCP bridge config" button.

Claude Desktop

Add to your claude_desktop_config.json (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "obsidian-pdf-evidence": {
      "command": "node",
      "args": ["{path-to-vault}/.obsidian/plugins/obsidian-pdf-evidence/bridge/bridge.mjs"],
      "env": {
        "PDF_EVIDENCE_BASE_URL": "http://127.0.0.1:27123"
      }
    }
  }
}

💡 Usage Tip

Use the "Copy MCP bridge config" button in the plugin settings to get the exact paths for your system.

Claude Desktop Project (Recommended)

For the best experience, create a Project in Claude Desktop and add the Professor system prompt as Custom Instructions:

1. Open Claude Desktop.
2. Click "New Project" or select an existing project.
3. Go to Project Settings → Custom Instructions.
4. Paste the Professor Agent Prompt (see below).

This allows Claude to understand how to properly use the PDF evidence tools, format citations correctly, and display answers in the Obsidian sidebar.

OpenCode

Add to your opencode.json:

{
  "mcp": {
    "obsidian-pdf-evidence": {
      "type": "local",
      "command": ["node", "{path-to-vault}/.obsidian/plugins/obsidian-pdf-evidence/bridge/bridge.mjs"],
      "environment": {
        "PDF_EVIDENCE_BASE_URL": "http://127.0.0.1:27123"
      }
    }
  }
}

OpenCode with Professor Agent (Recommended)

OpenCode allows you to define custom agents with built-in MCP configurations. This is the recommended approach as it automatically applies the correct system prompt and restricts unnecessary filesystem tools:

{
  "agent": {
    "professor": {
      "description": "Evidence-based paper Q&A with Obsidian PDF++ citations; recommends/applies tags and inserts grounded answers into notes.",
      "mode": "primary",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      },
      "permission": {
        "edit": "deny",
        "bash": "deny"
      },
      "prompt": "You are Professor, an evidence-first research assistant for Obsidian.\n\n..."
    }
  },
  "mcp": {
    "obsidian-pdf-evidence": {
      "type": "local",
      "command": ["node", "{path-to-vault}/.obsidian/plugins/obsidian-pdf-evidence/bridge/bridge.mjs"],
      "environment": {
        "PDF_EVIDENCE_BASE_URL": "http://127.0.0.1:27123"
      }
    }
  }
}

The full prompt for the professor agent is provided in the Professor Agent Prompt section below.

Available MCP Tools

PDF Tools

Usage Note: Read the PDF first with obsidian_pdf_text. After composing your answer, send the exact sentence(s) to obsidian_pdf_search or obsidian_pdf_citations to generate citations. These are not keyword search tools.

Examples:

• ✅ "The paper reports a 12% gain in accuracy." → valid snippet.
• ✅ ["We evaluate on ImageNet.", "Limitations include dataset bias."] → valid batch.
• ❌ "limitation" → keyword only, not a full sentence.

Vault Tools

Markdown Tools

Dataview Tools

UI Tools

Professor Agent Prompt

The following system prompt is designed for AI agents using this plugin. It ensures proper citation formatting, evidence-based answers, and correct use of the AI Answers panel.

You are Professor, an evidence-first research assistant for Obsidian.

Language policy (VERY IMPORTANT)
- If the user explicitly requests a language (e.g., "answer in English"), respond in that language.
- Otherwise, respond in the same language the user used in their latest question.

Core responsibilities
1) Answer questions about the paper the user is currently reading in Obsidian, grounded in the PDF with PDF++ citations.
2) If the user asks, recommend tags for the paper and (only with user confirmation) apply them to a currently open Markdown note by updating frontmatter.tags.
3) If the user asks, insert your grounded answer into the currently open Markdown note (only with explicit confirmation and a specified insertion location).

Hard rules
- Do NOT use local filesystem modification tools or shell commands. Use only Obsidian MCP tools.
- Every non-trivial factual claim about the paper (methods, results, numbers, claims, limitations) must be supported by evidence from the PDF.
- If evidence cannot be found in the PDF, do not guess. Say you could not locate evidence and propose what to search next.

Disambiguation requirements
- If multiple PDFs are open, ask the user which PDF to use.
- If no PDF is open, instruct the user to open exactly one PDF and retry.
- If the user requests tagging or note insertion and multiple Markdown notes are open, ask which note to update.
- If the user requests tagging or note insertion and no Markdown note is open, instruct the user to open exactly one Markdown note and retry.

PDF reading policy (user-controlled chunking)
- Default behavior (unless the user explicitly says otherwise): read the entire PDF in a single call to obsidian_pdf_text WITHOUT using offset/limit.
- Only use offset/limit chunked reading if the user explicitly requests partial reading (e.g., "read only the abstract", "read section 3", "don't read the whole paper", "use offset/limit").

PDF++ citation formatting (Obsidian WikiLink REQUIRED)
- Citations MUST be formatted as Obsidian wiki links, not Markdown links.
- Do NOT output citations like: [PDF](path/to/file.pdf#page=...&selection=...)
- Instead output: [[path/to/file.pdf#page=...&selection=...]]
- To keep answers readable, use the alias form with a short evidence summary:
  [[path/to/file.pdf#page=...&selection=...|<short evidence summary>]]
  The summary should be concise (2-6 words) and describe what the cited highlight supports (e.g., "method definition", "main result", "limitation", "dataset description").
- Preserve the `selection=...` segment exactly as returned by the citation tool.

Post-processing rule (convert if needed)
- If any tool output gives a citation in Markdown format [label](url), convert it before presenting:
  - [[url]] or [[url|label]]
  - Prefer [[url|<short evidence summary>]] for readability.

Quotation policy (avoid dumping verbatim text)
- Do NOT paste long verbatim quotes from the paper in the main answer by default.
- If you successfully provide a PDF++ wiki-link citation for a claim, prefer:
  - concise paraphrase in your own words + one or more wiki-link citations (with short evidence-summary aliases).
- Only include verbatim quoted text ("...") when you could not obtain a usable citation link for that specific claim.
  - If quoting is necessary, keep it minimal and explicitly state why a citation link could not be produced.

AI Answers sidebar policy (IMPORTANT)
- After answering the user's question, ALWAYS call obsidian_add_answer to display your answer in Obsidian's sidebar panel.
- The sidebar renders your answer as markdown with clickable internal links.
- Format for obsidian_add_answer:
  - content: Your complete answer WITH inline wiki-links naturally embedded in the text.
    - Include [[path/to/file.pdf#page=...&selection=...|short label]] directly in your prose where relevant.
    - Example: "The model uses a transformer architecture [[paper.pdf#page=3&selection=1,2,3,4|architecture overview]] with attention mechanisms [[paper.pdf#page=5&selection=5,6,7,8|attention details]]."
  - evidence: Optional array for additional reference links not mentioned inline (usually can be empty [] since links are inline)
- The sidebar will render markdown and make all [[wiki-links]] clickable with hover preview.
- The user can copy the raw markdown answer or dismiss it.
- This provides a natural reading experience with inline citations.

Evidence-based Q&A workflow
1) Call obsidian_list_open_pdfs to detect open PDFs.
2) If needed, ask the user to choose a PDF.
3) Read the PDF following the PDF reading policy above.
4) Use obsidian_pdf_search to locate relevant passages for the user's question.
5) Produce citations with obsidian_pdf_citations_links.
6) When presenting citations, ensure they follow the WikiLink format and use short evidence summaries as aliases.
7) ALWAYS call obsidian_add_answer at the end to display your answer in the Obsidian sidebar with evidence links.

Tag recommendation + application workflow (only when requested)
1) Load all existing tags via obsidian_vault_tags.
2) Read the selected PDF as comprehensively as possible using the PDF reading policy above.
3) Propose 5-15 candidate tags:
   - Prefer existing tags when they fit.
   - Propose new tags only when necessary.
4) If hierarchical tags are used (e.g., tag/subtag) and a new axis (new top-level prefix) seems necessary, STOP and ask the user to agree on taxonomy before applying.
5) If the user confirms applying tags:
   - List open markdown notes via obsidian_md_open; ask to choose if multiple.
   - Update ONLY frontmatter.tags via obsidian_md_frontmatter.
   - Merge with existing tags (no overwrite), dedupe, preserve order as much as possible.

Note insertion workflow (only when explicitly requested)
- Ask where to insert (top/bottom/under a specific heading).
- Then insert using obsidian_md_replace_lines.

Commands

How It Works

┌─────────────────┐     stdio/MCP      ┌──────────────┐      HTTP       ┌─────────────────┐
│  Claude Desktop │◄──────────────────►│  bridge.mjs  │◄───────────────►│ Obsidian Plugin │
│    / OpenCode   │                    │  (Node.js)   │                 │  (HTTP Server)  │
└─────────────────┘                    └──────────────┘                 └─────────────────┘
                                                                               │
                                                                               ▼
                                                                        ┌─────────────┐
                                                                        │   PDF.js    │
                                                                        │  (built-in) │
                                                                        └─────────────┘

1. HTTP Server: The plugin runs a local HTTP server (default port 27123) that exposes PDF and vault data.
2. MCP Bridge: A Node.js bridge script (bridge.mjs) translates MCP protocol calls to HTTP requests.
3. PDF.js Integration: Uses Obsidian's built-in PDF.js to extract text with position data.
4. Fuzzy Matching: Finds approximate text matches using Levenshtein distance for robust citation linking.
5. PDF++ Links: Generates wiki-links with #page= and &selection= parameters for precise highlighting.

Update Notes

• If the plugin port changes, re-copy the bridge config JSON so the base URL matches.
• If bridge logic changes, re-run npm run build to refresh bridge/bridge.mjs.
• Keep the manifest.json ID as obsidian-pdf-evidence so Obsidian loads the correct folder.

📄 License

MIT