{"id":30805540,"url":"https://github.com/aaronsb/obsidian-mcp-plugin","last_synced_at":"2026-05-17T06:18:09.350Z","repository":{"id":301591036,"uuid":"1009729416","full_name":"aaronsb/obsidian-mcp-plugin","owner":"aaronsb","description":"High-performance Model Context Protocol (MCP) server for Obsidian that provides AI tools with direct vault access through semantic operations and HTTP transport.","archived":false,"fork":false,"pushed_at":"2025-08-31T06:15:17.000Z","size":911,"stargazers_count":61,"open_issues_count":7,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-08-31T07:19:35.166Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaronsb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["aaronsb"]}},"created_at":"2025-06-27T15:59:38.000Z","updated_at":"2025-08-31T06:14:47.000Z","dependencies_parsed_at":"2025-06-27T17:39:46.138Z","dependency_job_id":"99b79f26-c455-4109-87ca-71e5ea2277f9","html_url":"https://github.com/aaronsb/obsidian-mcp-plugin","commit_stats":null,"previous_names":["aaronsb/obsidian-mcp-plugin"],"tags_count":104,"template":false,"template_full_name":null,"purl":"pkg:github/aaronsb/obsidian-mcp-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-mcp-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-mcp-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-mcp-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-mcp-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaronsb","download_url":"https://codeload.github.com/aaronsb/obsidian-mcp-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaronsb%2Fobsidian-mcp-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273842824,"owners_count":25177921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-06T00:58:48.775Z","updated_at":"2026-05-17T06:18:09.344Z","avatar_url":"https://github.com/aaronsb.png","language":"TypeScript","funding_links":["https://github.com/sponsors/aaronsb"],"categories":["📚 Projects (1974 total)"],"sub_categories":["MCP Servers"],"readme":"# Semantic Notes Vault MCP\n\n![GitHub stars](https://img.shields.io/github/stars/aaronsb/obsidian-mcp-plugin?style=social)\n![GitHub forks](https://img.shields.io/github/forks/aaronsb/obsidian-mcp-plugin?style=social)\n![Downloads](https://img.shields.io/github/downloads/aaronsb/obsidian-mcp-plugin/total?color=blue)\n![Latest Release](https://img.shields.io/github/v/release/aaronsb/obsidian-mcp-plugin?include_prereleases\u0026label=version)\n![License](https://img.shields.io/github/license/aaronsb/obsidian-mcp-plugin)\n\n📦 **[Available in the Obsidian Community Plugin directory →](https://community.obsidian.md/plugins/semantic-vault-mcp)**\n\n**Give AI semantic agency over your knowledge graph**\n\nThis plugin connects your Obsidian vault to AI assistants through MCP (Model Context Protocol), giving them the ability to understand and navigate your notes 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.\n\n**MCP (Model Context Protocol)** is the open standard that lets AI assistants interact with external tools and data sources. This plugin works with any MCP-compatible client including:\n- Claude Desktop (Anthropic)\n- Claude Code/Continue.dev (VS Code)\n- Any platform that supports local MCP servers\n\n## Why Semantic MCP?\n\nTraditional file access gives AI a narrow view - one document at a time. This plugin transforms that into **semantic agency**:\n\n- **Graph Navigation**: AI follows links between notes, understanding relationships and context\n- **Concept Discovery**: Semantic search finds related ideas across your vault\n- **Contextual Awareness**: AI understands where information lives in your knowledge structure\n- **Intelligent Synthesis**: Combine fragments from multiple notes to answer complex questions\n\n## Quick Start\n\n**Prerequisites:** You need an MCP-compatible AI client like Claude Desktop, Claude Code, or Continue.dev.\n\n### 1. Install the Plugin\n\n**Via Obsidian Community Plugins**\n- Open Settings → Community plugins → Browse\n- Search for \"Semantic Notes Vault MCP\"\n- Install and enable — or install straight from the [plugin listing](https://community.obsidian.md/plugins/semantic-vault-mcp)\n\n**Via BRAT** (for beta testing)\n- Install [BRAT](https://github.com/TfTHacker/obsidian42-brat)\n- Add beta plugin: `aaronsb/obsidian-mcp-plugin`\n\n### 2. Configure Your AI Client\n\nThree onboarding paths, ordered by audience. All three are also shown in the plugin's Settings tab with copy-ready values.\n\n**Claude Desktop — one-click `.mcpb` install (recommended)**\n\nDownload `obsidian-mcp-\u003cversion\u003e.mcpb` from the [latest release](https://github.com/aaronsb/obsidian-mcp-plugin/releases/latest), then either drag it onto the Claude Desktop window or double-click it. Claude Desktop opens an install dialog with two fields — paste the URL and API key shown in the plugin's Settings tab, hit Save, and you're done.\n\n\u003e *Cross-platform note:* `.mcpb` files install via Claude Desktop's bundled handler. If double-click doesn't trigger Claude on your system, drag the file onto Claude Desktop's window instead, or right-click → \"Open with…\" and pick Claude Desktop (then \"always open with\" if your OS asks). Behavior varies by platform: macOS usually auto-associates, Windows may need a one-time association, Linux varies by desktop environment.\n\n**Claude Code (CLI)**\n\n```bash\nclaude mcp add --transport http obsidian http://localhost:3001/mcp --header \"Authorization: Bearer YOUR_API_KEY\"\n```\n\n**Other MCP clients (Cline, Continue, custom integrations, multi-vault setups)**\n\nAdd an entry to the client's MCP config file — one entry per vault if you run multiple Obsidian instances on different ports:\n\n```json\n{\n  \"mcpServers\": {\n    \"obsidian-vault\": {\n      \"transport\": {\n        \"type\": \"http\",\n        \"url\": \"http://localhost:3001/mcp\",\n        \"headers\": {\n          \"Authorization\": \"Bearer YOUR_API_KEY\"\n        }\n      }\n    }\n  }\n}\n```\n\n**Advanced: custom `.mcpb` per vault**\n\nFor multi-vault setups that want one-click install per vault, clone this repo and run the maker:\n\n```bash\nnode scripts/make-mcpb.mjs\n# Prompts for display name, URL, and API key\n# Outputs obsidian-mcp-\u003cslug\u003e.mcpb with everything pre-filled\n```\n\nDrop the resulting bundle into Claude Desktop and click Install — no fields to type.\n\n### 3. Start Using\n\nOnce connected, simply chat with your AI assistant about your notes! For example:\n- \"What are my recent thoughts on project X?\"\n- \"Find connections between my psychology and philosophy notes\"\n- \"Summarize my meeting notes from this week\"\n- \"Create a new note linking my ideas about Y\"\n\nYour AI assistant now has these capabilities:\n- Navigate your vault's link structure\n- Search across all notes semantically\n- Read, edit, and create notes\n- Analyze your knowledge graph\n- Work with Dataview queries (if installed)\n- Manage Obsidian Bases (database views)\n\n## Core Tools\n\nThe plugin provides 8 semantic tool groups that give AI comprehensive vault access:\n\n| Tool | Purpose | Key Actions |\n|------|---------|-------------|\n| **📁 vault** | File operations | list, read, create, search, move, split, combine |\n| **✏️ edit** | Content modification | window editing, append, patch sections |\n| **👁️ view** | Content display | view files, windows, active note |\n| **🕸️ graph** | Link navigation | traverse, find paths, analyze connections |\n| **💡 workflow** | Contextual hints | suggest next actions based on state |\n| **📊 dataview** | Query notes | Execute DQL queries (if installed) |\n| **🗃️ bases** | Database views | Query and export Bases (if available) |\n| **ℹ️ system** | Vault info | Server status, commands, web fetch |\n\n## Documentation\n\nDetailed documentation for each tool and feature:\n\n- [📁 Vault Operations](docs/tools/vault.md) - File management and search\n- [✏️ Edit Operations](docs/tools/edit.md) - Content modification strategies  \n- [🕸️ Graph Navigation](docs/tools/graph.md) - Link traversal and analysis\n- [📊 Dataview Integration](docs/tools/dataview.md) - Query language support\n- [🔐 Security \u0026 Authentication](docs/security.md) - API keys and permissions\n- [🔧 Configuration](docs/configuration.md) - Server settings and options\n- [❓ Troubleshooting](docs/troubleshooting.md) - Common issues and solutions\n\n## The Semantic Advantage\n\nThis plugin doesn't just give AI access to files - it provides **semantic understanding**:\n\n### Example: Research Assistant\n```\nUser: \"Summarize my research on machine learning optimization\"\n\nAI uses semantic tools to:\n1. Search for notes with ML optimization concepts\n2. Traverse graph to find related papers and techniques  \n3. Follow backlinks to discover applications\n4. Synthesize findings from multiple connected notes\n```\n\n### Example: Knowledge Explorer\n```\nUser: \"What connections exist between my notes on philosophy and cognitive science?\"\n\nAI uses graph tools to:\n1. Find notes tagged with both topics\n2. Analyze shared concepts via graph traversal\n3. Identify bridge notes that connect domains\n4. Map the conceptual overlap\n```\n\n## Features\n\n### Semantic Search\n- Advanced query operators: `tag:`, `path:`, `content:`\n- Regular expressions and phrase matching\n- Relevance ranking and snippet extraction\n\n### Graph Intelligence\n- Multi-hop traversal with depth control\n- Backlink and forward-link analysis\n- Path finding between concepts\n- Tag-based navigation\n\n### Content Operations\n- Fuzzy text matching for edits\n- Structure-aware modifications (headings, blocks)\n- Batch operations (split, combine, move)\n- Template support\n\n### Integration\n- Dataview query execution\n- Bases database operations\n- Web content fetching\n- Read-only mode for safety\n\n## Plugin Settings\n\nAccess settings via: Settings → Community plugins → Semantic MCP\n\nKey configuration options:\n- **Server Ports**: HTTP (3001) and HTTPS (3443)\n- **Authentication**: API key protection\n- **Security**: Path validation and permissions\n- **Performance**: Connection pooling and caching\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/aaronsb/obsidian-mcp-plugin/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/aaronsb/obsidian-mcp-plugin/discussions)\n- **Sponsor**: [GitHub Sponsors](https://github.com/sponsors/aaronsb)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fobsidian-mcp-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaronsb%2Fobsidian-mcp-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaronsb%2Fobsidian-mcp-plugin/lists"}