Obsidian MCP Actor

The Obsidian MCP Actor bridges the gap between your local Obsidian knowledge base and the web. It uses Apify's powerful scraping capabilities (Crawlee) to fetch content from the internet, uses LLMs (OpenAI) to generate intelligent tags and summaries, downloads all media assets, and securely pushes the newly created notes directly into your local Obsidian vault via the Model Context Protocol (MCP).

---

🌟 Key Features

1. Automated Note Creation (Reader Mode)

Scrapes any webpage and transforms its main content into clean, GitHub-Flavored Markdown. It uses Mozilla's Readability.js (the exact engine behind Firefox's Reader View) to instantly strip out all advertisements, navigation sidebars, cookie banners, and footers, leaving only the pure article text.

2. Media & Image Downloading (Local Resilience)

No more broken image links! If enabled, the Actor will automatically detect all images in the scraped article, download them, and save them directly to an attachments folder inside your Obsidian Vault. The Markdown will then be rewritten to use native Obsidian embeds (e.g., ![[image.jpg]]).

3. Intelligent Tagging & Summarization (Optional AI Extraction)

Uses OpenAI to read the scraped content and generate metadata for you. By default, it generates a brief summary and relevant tags. You can easily pass a Custom AI Prompt to extract specialized information (e.g., "Extract all quotes", "List the top 5 companies mentioned", or "Format the output into a specific Obsidian YAML template").

4. High-Performance & Cost-Effective

The headless browser is configured to actively block the loading of heavy CSS, fonts, and tracking scripts, drastically reducing execution time and saving your Apify compute credits.

5. Seamless Obsidian Integration

Connects directly to your Obsidian vault's local MCP Server using Server-Sent Events (SSE). It creates the .md files directly on your local hard drive—no manual copying and pasting required.

---

🛠️ Architecture: How it works

Because Obsidian runs locally on your computer, the Apify Actor (running in the cloud) needs a secure way to talk to it.

1. The MCP Server: You install an MCP Server plugin in your Obsidian vault. This opens a local port (e.g., http://127.0.0.1:3000).
2. The Secure Tunnel: You use a tool like ngrok to expose that local port to the internet securely (e.g., https://1a2b3c4d.ngrok.app).
3. The MCP Client: The Apify Actor acts as the client. It connects to your ngrok URL.
4. The Scraping Loop:
   • The Actor visits a URL from your startUrls list.
   • It extracts and cleans the text via Readability.js.
   • It downloads all images and saves them to your vault via the MCP write_file tool.
   • It sends the final Markdown note to your vault using the MCP create_note or write_file tool.

---

🚀 Step-by-Step Setup Guide

Phase 1: Obsidian Setup

1. Open your Obsidian vault.
2. Install an MCP Server plugin (such as obsidian-mcp or cyanheads/obsidian-mcp-server) via the Community Plugins tab, or manually if it's in early development.
3. Enable the plugin. Take note of the port it runs on (usually 3000 or 3001).

Phase 2: Exposing the Server (ngrok)

To allow Apify to reach your local computer, we need a tunnel.

1. Download and install ngrok.
2. Run the following command in your terminal to expose your MCP server port:

   $ngrok http 3000
   

3. Copy the secure HTTPS URL ngrok provides (e.g., https://1a2b3c4d.ngrok.app). Keep this terminal window open while you want the integration to work.

Phase 3: Apify Setup

1. Deploy this Actor to your Apify account.
2. In the Actor's Input configuration, configure the following:
   • Start URLs: Add the web pages you want to scrape.
   • Obsidian MCP Server URL: Paste your ngrok URL here, appending /sse (e.g., https://1a2b3c4d.ngrok.app/sse).
   • Target Folder: Where notes should be saved in your vault (e.g., Research/Web).

Phase 4: Optional Features Setup

• Image Downloading: Toggle Download Images locally and set your Attachment Folder (e.g., Research/Attachments).
• AI Extraction: Toggle Enable AI Extraction and paste your OpenAI API Key. You can leave the Custom AI Prompt blank for default summarization, or write your own specific instructions.

---

⚙️ Input Parameters Reference

Parameter	Type	Required	Description
startUrls	Array	Yes	The list of URLs you want to scrape and turn into notes.
obsidianMcpUrl	String	Yes	The public URL of your Obsidian MCP Server (e.g., https://xyz.ngrok.app/sse).
obsidianMcpApiKey	String	No	If your MCP server requires an authorization token.
targetFolder	String	Yes	The folder in your Obsidian vault where notes will be saved.
downloadImages	Boolean	No	Check to download all images from the article directly to your vault.
attachmentFolder	String	No	The folder for downloaded images. Only used if downloadImages is true.
aiExtraction	Boolean	No	Toggle to enable LLM-based summaries and tags.
aiPrompt	String	No	Override the default extraction prompt to get exactly the data you want.
openaiApiKey	String	No	Required if AI extraction is enabled.

---

⚠️ Troubleshooting & FAQs

Q: The Actor fails immediately with a "Failed to connect" error.

• Ensure your ngrok terminal is running.
• Ensure your Obsidian app is open and the MCP plugin is enabled.
• Check that the obsidianMcpUrl in the Apify input ends with /sse if your server uses Server-Sent Events.

Q: Images are not downloading or rendering.

• Ensure your attachmentFolder exists in Obsidian. Some MCP servers cannot create nested folders automatically.
• Check if your MCP server supports writing base64 binary files via the write_file tool. If the images appear as text files containing base64 strings in your vault, the server may require an update to support binary encoding.

Q: AI Extraction isn't working.

• Ensure your openaiApiKey is valid and has sufficient credits.
• If you used a custom prompt, ensure it explicitly asks for a JSON output with summary and tags keys, otherwise the parser may fail.

---

📝 Example Output Note

---
title: "The Future of AI Agents"
source: https://example.com/future-ai-agents
date_scraped: 2025-10-22
tags: [artificialintelligence, agents, future]
---

# The Future of AI Agents

> **AI Summary**: This article discusses the evolution of AI agents and how they are transitioning from simple chat interfaces to autonomous systems that can interact with APIs and local environments.

## Content

Here is an image of the architecture:

![[img_7f8a9b2c.jpg]]

[Clean, reader-mode markdown representation of the article...]