# Enhanced Obsidian MCP Server - 25 Advanced AI Tools
[](https://badge.fury.io/js/@jianruidutong%2Fobsidian-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[English](./README.md) | [δΈζ](./README.zh.md)
## π Overview
The **Enhanced Obsidian MCP Server** is a powerful Model Context Protocol (MCP) server designed for seamless integration between AI models and Obsidian knowledge bases. Provides **25 powerful tools** for intelligent knowledge management, automated content analysis, and smart linking capabilities.
### β¨ Core Features
- π **Seamless Obsidian Integration:** Direct access to Obsidian knowledge base through MCP protocol
- π **Complete Note Management:** Read, create, update, and delete notes with advanced text replacement features
- π **Folder Operations:** Create, rename, move, and delete folders with full hierarchy support
- π **Intelligent Search:** Full-text search across all file types with smart scoring
- π€ **AI Analysis:** Revolutionary strategic insights using TF-IDF framework
- π **Auto Backlink Generation:** Revolutionary intelligent detection of note names and conversion to wikilinks
- β‘ **Precise Editing:** Advanced PATCH operations with heading and block-level positioning
- π **Dual API Strategy:** Obsidian REST API combined with file system fallback for maximum reliability
- π― **Context Optimization:** Intelligent content summarization for LLM context length management
- π **Batch Processing:** Efficient bulk operations with progress tracking
### β¨ New Features
- π§ **15 New AI-Enhanced Tools** for intelligent content analysis
- π **Smart Auto-Linking** with advanced pattern recognition
- π **Knowledge Graph Generation** for visualizing note relationships
- π·οΈ **Advanced Tag Management** with intelligent suggestions
- π **Template System** for consistent note creation
- π **Content Similarity Analysis** using TF-IDF and cosine similarity
- π **Relationship Analysis** for discovering hidden connections
## π οΈ Complete Tool Suite (25 Tools)
### π **Core Note Management (10 Tools)**
#### π **Note Operations**
| Tool | Description | Detailed Functionality |
|------|-------------|------------------------|
| `list_notes` | List all notes in vault with optional folder filtering | Browse vault contents, filter by specific folders, get note metadata (size, dates, paths) |
| `read_note` | Read individual note content | Retrieve complete note content with metadata, file statistics, and modification history |
| `read_multiple_notes` | Batch read multiple notes simultaneously | Efficiently load multiple notes at once, perfect for content analysis or bulk operations |
| `create_note` | Create new notes with content | Generate new markdown files with specified content, automatic directory creation |
| `update_note` | Advanced content editing with precise positioning | Edit notes with surgical precision - replace text, insert at specific positions, delete sections |
| `delete_note` | Remove notes from vault | Safely delete notes with confirmation, maintains vault integrity |
| `move_note` | Rename or relocate notes | Move notes between folders, rename files, automatic link updates |
#### π **Folder & Organization**
| Tool | Description | Detailed Functionality |
|------|-------------|------------------------|
| `manage_folder` | Full folder operations (create/rename/move/delete) | Complete folder management - create nested structures, reorganize vault hierarchy |
| `search_vault` | Full-text search across all content | Powerful search with regex support, context snippets, relevance scoring |
| `auto_backlink_vault` | Intelligent auto-linking with pattern recognition | Scan entire vault, detect note names in content, convert to [[wikilinks]] automatically |
### π·οΈ **Tag Management System (3 Tools)**
| Tool | Description | Detailed Functionality |
|------|-------------|------------------------|
| `add_tags` | Add multiple tags to notes | Insert hashtags into note frontmatter or content, support for nested tags (e.g., #project/web) |
| `list_tags` | List all tags with usage statistics | Comprehensive tag inventory with usage counts, sorting options, tag hierarchy analysis |
| `search_by_tags` | Advanced tag-based search with AND/OR operators | Complex tag queries - find notes with specific tag combinations, Boolean logic support |
### π **Template System (4 Tools)**
| Tool | Description | Detailed Functionality |
|------|-------------|------------------------|
| `create_template` | Create reusable note templates with variables | Design dynamic templates with {{variables}}, support for dates, titles, custom placeholders |
| `list_templates` | Browse available templates | View all saved templates with metadata, usage statistics, and variable information |
| `apply_template` | Apply templates with variable substitution | Generate new notes from templates, automatic variable replacement, custom value injection |
| `delete_template` | Remove unused templates | Clean up template library, maintain template organization |
### π§ **AI Content Analysis (4 Tools)**
| Tool | Description | Detailed Functionality |
|------|-------------|------------------------|
| `extract_keywords` | Extract key terms using TF-IDF algorithm | Identify important keywords and phrases, statistical relevance scoring, configurable result count |
| `generate_summary` | Create intelligent content summaries | Automatic text summarization, extractive summary generation, customizable length |
| `suggest_tags` | AI-powered tag recommendations | Analyze content and suggest relevant tags, learn from existing tagging patterns |
| `find_similar_notes` | Discover similar content using cosine similarity | Content-based similarity matching, semantic analysis, threshold-based filtering |
### π **Knowledge Graph & Analytics (4 Tools)**
| Tool | Description | Detailed Functionality |
|------|-------------|------------------------|
| `analyze_note_relationships` | Comprehensive relationship mapping | Map connections between notes, analyze link patterns, identify knowledge clusters |
| `generate_knowledge_graph` | Export graph data for visualization tools | Generate network data in JSON/Cytoscape formats, node/edge definitions, ready for D3.js/Gephi |
| `find_orphan_notes` | Identify isolated content | Detect notes without links, find disconnected content, vault completeness analysis |
| `suggest_connections` | AI-powered connection recommendations | Recommend potential links based on content similarity, discover hidden relationships |
## π Quick Start
### Option 1: NPM Installation (Recommended)
**Install globally:**
```bash
npm install -g @jianruidutong/obsidian-mcp
```
**Or use npx (no installation required):**
```bash
npx @jianruidutong/obsidian-mcp
```
### Option 2: From Source
**Clone and build:**
```bash
git clone https://github.com/jianruidutong/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build
npm start
```
### Option 3: Docker Installation
**Quick start with Docker:**
```bash
git clone https://github.com/jianruidutong/obsidian-mcp.git
cd obsidian-mcp
cp .env.example .env
# Edit .env with your vault settings
docker-compose up -d
```
> π **For detailed installation instructions, see [Installation Guide](./INSTALLATION.md)**
## βοΈ Configuration
### MCP Client Configuration
#### Option 1: NPM Installation Configuration
```json
{
"mcpServers": {
"obsidian-mcp": {
"command": "npx",
"args": ["-y", "@jianruidutong/obsidian-mcp"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
"OBSIDIAN_API_TOKEN": "your_api_token",
"OBSIDIAN_API_PORT": "27123"
}
}
}
}
```
#### Option 2: Source Installation Configuration
```json
{
"mcpServers": {
"obsidian-mcp": {
"command": "node",
"args": ["/path/to/obsidian-mcp/build/index.js"],
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
"OBSIDIAN_API_TOKEN": "your_api_token",
"OBSIDIAN_API_PORT": "27123"
}
}
}
}
```
#### Option 3: Docker Installation Configuration
```json
{
"mcpServers": {
"obsidian-mcp": {
"command": "docker",
"args": [
"exec",
"-i",
"obsidian-mcp-server",
"npm",
"start"
],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
**Note:** For Docker, environment variables are configured in `.env` file or `docker-compose.yml`.
### Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|----------|
| `OBSIDIAN_VAULT_PATH` | Path to your Obsidian vault | β
Yes | - |
| `OBSIDIAN_API_TOKEN` | Local REST API token | β
Yes | - |
| `OBSIDIAN_API_PORT` | API port number | π§ Recommended | 27123 |
> π§ **For all configuration options, see [Configuration Reference](./docs/configuration.md)**
## π Prerequisites
1. **Node.js** (v16 or higher)
2. **Obsidian Desktop Application**
3. **Local REST API Plugin** installed in Obsidian
### Setting Up Obsidian Local REST API
1. Install the "Local REST API" plugin in Obsidian
2. Generate an API token in the plugin settings
3. Note the port number (default: 27123)
4. Ensure the plugin is enabled
## π Documentation
- [π Installation Guide](./INSTALLATION.md) - Complete installation instructions for all methods
- [π§ Configuration Reference](./docs/configuration.md) - Detailed configuration options and troubleshooting
- [π οΈ API Documentation](./docs/api.md) - Complete API reference for all 25 tools
- [π Usage Examples](./docs/examples.md) - Practical examples and real-world scenarios
## π€ Contributing
We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
### Development Setup
```bash
git clone https://github.com/jianruidutong/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run dev
```
## π Troubleshooting
### Common Issues
**Connection refused error:**
- Ensure Obsidian Local REST API plugin is installed and enabled
- Verify the API token and port number
- Check that Obsidian is running
**Permission denied:**
- Verify vault path permissions
- Ensure the API token has proper access rights
**Environment variables not working:**
- Use the `OBSIDIAN_` prefix for all environment variables
- Restart your MCP client after configuration changes
> π **For detailed troubleshooting, see [Configuration Reference](./docs/configuration.md)**
## π License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## π Acknowledgments
- [Model Context Protocol](https://github.com/anthropics/model-context-protocol) by Anthropic
- [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) plugin
- The original project address: https://github.com/newtype-01/obsidian-mcp
## π Support
- π [Report Issues](https://github.com/jianruidutong/obsidian-mcp/issues)
- π¬ [Discussions](https://github.com/jianruidutong/obsidian-mcp/discussions)
---
β **Star this repository if you find it useful!** β
