QUICKSTART.md•4.74 kB
# Quick Start Guide
Get your Obsidian MCP server running in 5 minutes!
## Prerequisites Checklist
- [ ] Obsidian installed and running
- [ ] [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) installed in Obsidian
- [ ] Python 3.10+ installed
- [ ] `uv` installed (or use pip as alternative)
## Step 1: Install Local REST API Plugin in Obsidian
1. Open Obsidian
2. Go to Settings → Community plugins
3. Turn off "Restricted mode" if needed
4. Click "Browse" and search for "Local REST API"
5. Install the plugin by coddingtonbear
6. Enable the plugin
7. Go to plugin settings and **copy your API key**
8. Note the port (default: 27124)
## Step 2: Set Up the MCP Server
### Option A: Using uv (Recommended)
```bash
cd custom-obsidian-mcp
uv sync
```
### Option B: Using pip
```bash
cd custom-obsidian-mcp
pip install -e .
```
## Step 3: Configure Environment
Create a `.env` file:
```bash
cp .env.example .env
```
Edit `.env` and add your API key:
```bash
OBSIDIAN_API_KEY=your-actual-api-key-here
OBSIDIAN_HOST=127.0.0.1
OBSIDIAN_PORT=27124
```
## Step 4: Verify Installation
```bash
python verify_installation.py
```
You should see ✅ checkmarks for all tests.
## Step 5: Configure Your LLM Client
### For Claude Desktop
Find your config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Add this configuration:
```json
{
"mcpServers": {
"obsidian": {
"command": "uvx",
"args": ["custom-obsidian-mcp"],
"env": {
"OBSIDIAN_API_KEY": "your-actual-api-key-here",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124"
}
}
}
}
```
**Using pip instead of uv?** Change the command:
```json
{
"mcpServers": {
"obsidian": {
"command": "python",
"args": ["-m", "custom_obsidian_mcp.server"],
"env": {
"OBSIDIAN_API_KEY": "your-actual-api-key-here",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124"
}
}
}
}
```
### For Perplexity
Configure similarly in Perplexity's MCP settings.
## Step 6: Restart and Test
1. **Restart your LLM client** (Claude Desktop, etc.)
2. Verify the MCP server appears in available tools
3. Try a simple command:
```
"List the files in my Obsidian vault"
```
If you see your files listed, **you're ready to go!** 🎉
## First Zettelkasten Note
Try this workflow:
1. **Search first:**
```
"Search my vault for notes about [your topic]"
```
2. **Create atomic note:**
```
"Create a new Zettelkasten note about [concept] with proper tags"
```
3. **Link to related notes:**
```
"Add links to related notes in the 'Related Concepts' section"
```
## Troubleshooting
### Connection Failed
**Problem:** Can't connect to Obsidian
**Solutions:**
1. Is Obsidian running? ✅
2. Is Local REST API plugin enabled? ✅
3. Is the API key correct? Check for spaces ✅
4. Try restarting Obsidian ✅
### Module Not Found
**Problem:** `ModuleNotFoundError: No module named 'custom_obsidian_mcp'`
**Solutions:**
```bash
# Reinstall
pip install -e .
# Or
uv sync
# Verify
python -c "from custom_obsidian_mcp.server import mcp; print('OK')"
```
### MCP Server Not Showing in Client
**Problem:** Tools don't appear in Claude/Perplexity
**Solutions:**
1. Check config file path is correct
2. Verify JSON syntax (use a JSON validator)
3. Restart the client application completely
4. Check client logs for errors
### Authentication Error
**Problem:** "Authentication failed"
**Solutions:**
1. Regenerate API key in Obsidian plugin settings
2. Copy-paste carefully (no extra spaces)
3. Update both `.env` and client config files
4. Restart Obsidian
## Next Steps
- Read the [USAGE_EXAMPLES.md](USAGE_EXAMPLES.md) for Zettelkasten workflows
- Read the [README.md](README.md) for full tool documentation
- Start with simple operations before complex workflows
- Test in a practice vault before using your main Zettelkasten
## Getting Help
1. Run `python verify_installation.py` to diagnose issues
2. Check Obsidian's console for REST API errors
3. Review client logs for MCP connection issues
4. Test the REST API directly: `curl -k -H "Authorization: Bearer YOUR_KEY" https://127.0.0.1:27124/vault/`
## Tips for Success
✅ **Always search before creating** - Avoid duplicate notes
✅ **Use CREATE mode** - Won't accidentally overwrite
✅ **Start simple** - List files, then search, then create
✅ **Test in safe vault** - Practice before using main vault
✅ **Read tool descriptions** - Understand what each tool does
---
**Happy note-taking! Your Zettelkasten is now AI-powered! 🚀📝**