obsidian-plugin/aaronsb_obsidian-mcp-plugin
1
0
Fork 0
mirror of https://github.com/aaronsb/obsidian-mcp-plugin.git synced 2026-07-22 06:45:14 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
aaronsb_obsidian-mcp-plugin/README.md
Aaron Bockelie 7fedcd9bb6 docs: Simplify README with semantic value proposition focus 
- Replace complex technical README with cleaner, simpler version
- Focus on semantic agency and graph navigation as core value
- Move detailed documentation to docs/ subdirectory
- Create tool-specific documentation for vault and graph operations
- Emphasize why semantic MCP matters for AI knowledge access
2025-08-31 00:54:07 -05:00

5.4 KiB
Raw Blame History

Obsidian MCP Plugin

Give AI semantic agency over your knowledge graph

This plugin enables AI assistants (Claude, ChatGPT, etc.) to understand and navigate your Obsidian vault as a connected knowledge graph, not just isolated files. Through semantic hints and graph traversal, AI gains the agency to explore concepts, follow connections, and synthesize information across your entire vault.

Why Semantic MCP?

Traditional file access gives AI a narrow view - one document at a time. This plugin transforms that into semantic agency:

  • Graph Navigation: AI follows links between notes, understanding relationships and context
  • Concept Discovery: Semantic search finds related ideas across your vault
  • Contextual Awareness: AI understands where information lives in your knowledge structure
  • Intelligent Synthesis: Combine fragments from multiple notes to answer complex questions

Quick Start

1. Install the Plugin

Via Obsidian Community Plugins (coming soon)

  • Open Settings → Community plugins
  • Search for "Semantic MCP"
  • Install and enable

Via BRAT (for beta testing)

  • Install BRAT
  • Add beta plugin: aaronsb/obsidian-mcp-plugin

2. Configure Your AI Client

Claude Desktop

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3001/mcp"]
    }
  }
}

With Authentication (if enabled in plugin settings)

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://localhost:3443/mcp",
        "--header",
        "Authorization:${AUTH}"
      ],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "AUTH": "Bearer YOUR_API_KEY"
      }
    }
  }
}

3. Start Using

Once connected, your AI can:

  • Navigate your vault's link structure
  • Search across all notes semantically
  • Read, edit, and create notes
  • Analyze your knowledge graph
  • Work with Dataview queries
  • Manage Obsidian Bases (database views)

Core Tools

The plugin provides 8 semantic tool groups that give AI comprehensive vault access:

Tool Purpose Key Actions
📁 vault File operations list, read, create, search, move, split, combine
✏️ edit Content modification window editing, append, patch sections
👁️ view Content display view files, windows, active note
🕸️ graph Link navigation traverse, find paths, analyze connections
💡 workflow Contextual hints suggest next actions based on state
📊 dataview Query notes Execute DQL queries (if installed)
🗃️ bases Database views Query and export Bases (if available)
ℹ️ system Vault info Server status, commands, web fetch

Documentation

Detailed documentation for each tool and feature:

The Semantic Advantage

This plugin doesn't just give AI access to files - it provides semantic understanding:

Example: Research Assistant

User: "Summarize my research on machine learning optimization"

AI uses semantic tools to:
1. Search for notes with ML optimization concepts
2. Traverse graph to find related papers and techniques  
3. Follow backlinks to discover applications
4. Synthesize findings from multiple connected notes

Example: Knowledge Explorer

User: "What connections exist between my notes on philosophy and cognitive science?"

AI uses graph tools to:
1. Find notes tagged with both topics
2. Analyze shared concepts via graph traversal
3. Identify bridge notes that connect domains
4. Map the conceptual overlap

Features

Semantic Search

  • Advanced query operators: tag:, path:, content:
  • Regular expressions and phrase matching
  • Relevance ranking and snippet extraction

Graph Intelligence

  • Multi-hop traversal with depth control
  • Backlink and forward-link analysis
  • Path finding between concepts
  • Tag-based navigation

Content Operations

  • Fuzzy text matching for edits
  • Structure-aware modifications (headings, blocks)
  • Batch operations (split, combine, move)
  • Template support

Integration

  • Dataview query execution
  • Bases database operations
  • Web content fetching
  • Read-only mode for safety

Plugin Settings

Access settings via: Settings → Community plugins → Semantic MCP

Key configuration options:

  • Server Ports: HTTP (3001) and HTTPS (3443)
  • Authentication: API key protection
  • Security: Path validation and permissions
  • Performance: Connection pooling and caching

Support

License

MIT