mcp-obsidian-universal by breannasalah - MCP Server

Obsidian Universal MCP Server

A universal Model Context Protocol (MCP) server for Obsidian that works with all major AI platforms: Claude, ChatGPT, Gemini, Grok, and Perplexity.

🌟 Features

✅ Universal Compatibility: Works with Claude, ChatGPT, Gemini, Grok, and Perplexity
🔒 OAuth Ready: Infrastructure for secure authentication (extensible)
📚 Full Vault Access: Read, write, search, and manage your Obsidian notes
🏷️ Smart Tag Handling: Automatic extraction from frontmatter and content
🔍 Powerful Search: Regex-based search across all notes
🌐 HTTP Transport: Remote server for maximum compatibility
🚀 Zero Obsidian Plugins: Works directly with your vault files

🛠️ Installation

Prerequisites

Node.js 18.0.0 or later
An Obsidian vault

Setup

Clone or download this repository
```
cd ~/Projects/mcp-obsidian-universal
```
Install dependencies
```
npm install
```

Configure environment

cp .env.example .env

Edit .env and set your vault path:

OBSIDIAN_VAULT_PATH=/Users/breannasalah/Obsidian_Vault_3
PORT=3000
HOST=localhost

Build the server
```
npm run build
```
Start the server
```
npm start
```

You should see:

🚀 Obsidian Universal MCP Server running on http://localhost:3000
📚 Vault path: /Users/breannasalah/Obsidian_Vault_3
🔧 MCP SSE endpoint: http://localhost:3000/sse
💚 Health check: http://localhost:3000/health

🤖 Platform Configuration

1. Claude Desktop

Setup:

Open Claude Desktop configuration:

# macOS
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

Add the server configuration:

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Restart Claude Desktop

Usage:

"List all my notes in the Projects folder"
"Search for notes mentioning 'AI' and create a summary"
"Create a new note in Ideas/2025.md with my brainstorm"

2. ChatGPT (Developer Mode)

Requirements: ChatGPT Pro, Business, Enterprise, or Edu plan

Setup:

Open ChatGPT Settings → Connectors → Advanced → Developer Mode
Click "Add Connector"
Configure:
- Name: Obsidian Universal
- Server URL: http://localhost:3000/sse
- Type: Remote MCP Server
Save and enable the connector

Usage:

"Show me all notes tagged with #projects"
"Read the content of my daily note"
"Search my vault for references to quantum computing"

3. Gemini CLI

Setup:

Install Gemini CLI:

npm install -g @google/gemini-cli@latest

Configure MCP server in ~/.gemini/settings.json:

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:3000/sse",
      "description": "Obsidian vault access"
    }
  }
}

Start Gemini CLI:
```
gemini
```

Usage:

@obsidian list my notes in the Research folder
@obsidian search for "machine learning" in my vault
@obsidian create a note with today's learnings

4. Grok (xAI SDK)

Setup (Python):

import os
from xai_sdk import Client
from xai_sdk.tools import mcp

client = Client(api_key=os.getenv("XAI_API_KEY"))

chat = client.chat.create(
    model="grok-4-1-fast",
    tools=[
        mcp(
            server_url="http://localhost:3000/sse",
            server_label="obsidian",
            server_description="Access to Obsidian vault"
        ),
    ],
)

chat.append({"role": "user", "content": "List all my notes"})
for response, _ in chat.stream():
    print(response.choices[0].message.content)

Usage:

"Use the obsidian tool to find all notes about AI projects"
"Read my daily note and summarize it"
"Create a new note with research findings"

5. Perplexity (Mac App)

Requirements: Paid Perplexity subscription

Setup:

Open Perplexity Mac App
Go to Settings → Connectors
Click "Add Connector"
Configure as Remote MCP:
- Server URL: http://localhost:3000/sse
- Name: Obsidian
Enable the connector in the Sources dropdown

Usage:

"Show me my project notes from last week"
"Search my vault for blockchain articles"
"Create a new note about today's meeting"

📖 Available Tools

`list_notes`

List all notes in the vault, optionally filtered by folder.

Parameters:

folder (optional): Folder path relative to vault root
recursive (optional): Whether to include subdirectories (default: true)

Example:

{
  "folder": "Projects",
  "recursive": true
}

`read_note`

Read a specific note with frontmatter and tags.

Parameters:

path (required): Path to note (e.g., "folder/note.md")

Example:

{
  "path": "Daily/2025-12-01.md"
}

`write_note`

Create or update a note.

Parameters:

path (required): Where to save the note
content (required): Markdown content
frontmatter (optional): YAML frontmatter as JSON object

Example:

{
  "path": "Ideas/new-project.md",
  "content": "# New Project\n\nDescription here",
  "frontmatter": {
    "tags": ["projects", "ideas"],
    "date": "2025-12-01"
  }
}

`delete_note`

Permanently delete a note.

Parameters:

path (required): Path to note to delete

`search_notes`

Search vault content (supports regex).

Parameters:

query (required): Search query

Example:

{
  "query": "machine learning"
}

`get_vault_stats`

Get vault statistics (total notes, folders).

No parameters required.

🔧 Development

Run in development mode:

npm run dev

Test the server:

# Health check
curl http://localhost:3000/health

# Test with MCP Inspector
npx @modelcontextprotocol/inspector

🔐 Security Notes

Local Network Only: By default, the server only accepts connections from localhost
No Authentication: Currently no auth layer - server trusts local clients
File System Access: Server has full read/write access to your vault
Future: OAuth implementation planned for remote access scenarios

🚀 Roadmap

OAuth 2.0 implementation for secure remote access
Webhook support for real-time updates
Advanced search (semantic, fuzzy)
Batch operations
Obsidian plugin integration for live sync
Support for attachments and images

📝 License

MIT

🙏 Acknowledgments

Built on the Model Context Protocol standard by Anthropic. Inspired by the Obsidian community's amazing MCP server implementations.

💬 Support

Issues: GitHub Issues
Questions: Open a discussion
Contributions: PRs welcome!