otherdefense/obsidian-intelligent-mcp

🤖 Obsidian Intelligent MCP Server

Advanced Model Context Protocol server for intelligent Obsidian vault management

🌟 Features

🔍 Semantic Search with Context7 Awareness

• Vector-based note discovery using ChromaDB and SentenceTransformers
• Enhanced contextual understanding through Context7 integration
• Advanced filtering by folders, tags, and metadata

🤖 AI-Powered Note Management

• Intelligent note creation with auto-organization
• Smart tagging and categorization
• Template-aware note generation
• Link suggestions based on content similarity

📊 Comprehensive Analytics

• Vault statistics and trend analysis
• Usage patterns and metrics
• Performance monitoring and health checks

🔗 MCP Protocol Compliance

• Full MCP 1.13.0 specification support
• 9 comprehensive tools for note operations
• Resource exposure for vault structure and analytics
• Multi-client support (Claude Desktop, Continue, etc.)

🚀 Quick Start

Prerequisites

• Python 3.13+ (required for async features)
• Git for cloning the repository
• Obsidian vault to manage

Installation

# Clone the repository
git clone https://github.com/odg8888/obsidian-intelligent-mcp.git
cd obsidian-intelligent-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set your Obsidian vault path
export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"

# Test the installation
python test_server.py

Launch Server

# Development mode
./launch_mcp_server.sh

# Debug mode
./launch_mcp_server.sh --debug

# Or directly
python main.py

🔧 MCP Tools Available

🖥️ Client Configuration

Claude Desktop

Create or edit ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-intelligent-mcp": {
      "command": "python",
      "args": ["/path/to/obsidian-intelligent-mcp/main.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Continue IDE

Add to your Continue configuration:

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian-intelligent-mcp/main.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Multiple MCP Servers

Integrate with existing MCP setup:

{
  "mcpServers": {
    "context7": {
      "command": "/home/user/.nvm/versions/node/v24.3.0/bin/context7-mcp",
      "args": [],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    },
    "obsidian-intelligent-mcp": {
      "command": "python",
      "args": ["/path/to/obsidian-intelligent-mcp/main.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

🌍 Environment Variables

🧪 Testing

Run All Tests

# Basic functionality test
python test_server.py

# Comprehensive tool testing
python test_mcp_tools.py

# Related notes functionality
python test_related_notes.py

Performance Testing

# Test with large vault
OBSIDIAN_VAULT_PATH="/path/to/large/vault" python test_server.py

# Memory profiling
MCP_LOG_LEVEL=DEBUG python test_mcp_tools.py

🔒 Security & Privacy

• Local Processing: All AI operations run on your device
• No External Calls: Embeddings generated locally
• Vault Boundaries: Only accesses configured vault path
• Input Validation: Comprehensive input sanitization
• Path Security: Directory traversal protection

📈 Performance

• Response Time: <200ms for typical operations
• Memory Usage: ~500MB for large vaults
• Concurrent Clients: Supports 10+ simultaneous connections
• Embedding Generation: ~100ms per note
• Search Latency: ~50ms for queries

🐛 Troubleshooting

Common Issues

Python Version

python --version  # Should be 3.13+

Virtual Environment

source .venv/bin/activate
pip list | grep mcp

Vault Path

echo $OBSIDIAN_VAULT_PATH
ls -la "$OBSIDIAN_VAULT_PATH"

Permissions

chmod +x launch_mcp_server.sh
chmod +x main.py

Debug Mode

MCP_LOG_LEVEL=DEBUG python main.py

Reset Vector Store

rm -rf .chroma_db/
python main.py  # Will rebuild automatically

📝 Usage Examples

Search Notes

Search my notes for "project management best practices"

Create Note

Create a note called "MCP Integration Guide" with setup instructions

Find Related Notes

Find notes related to my "AI Development" note

Get Vault Statistics

Show me comprehensive statistics about my Obsidian vault

Auto-organize

Organize all notes in my "Projects" folder with better tags and links

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

• Model Context Protocol: Anthropic's MCP specification
• ChromaDB: Vector database for semantic search
• SentenceTransformers: Embedding models
• Obsidian: Note-taking and knowledge management

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See the 01-Projects/Obsidian-Intelligent-MCP/ folder in your vault

Obsidian Intelligent MCP Server v1.0
Transform your Obsidian vault with AI-powered intelligence