First HTTP-native MCP server for Obsidian - Works with Claude Code CLI, Codex, Gemini without stdio bugs
npm install obsidian-http-mcp> Finally use Claude Code to manage your Obsidian notes - no more crashes or broken pipes
The first HTTP-native MCP server for Obsidian that solves stdio transport bugs affecting Claude Code CLI (#3071, #9176, #9662)
Also compatible with: Claude Desktop, Codex, Gemini, and other MCP clients
---
First HTTP-native MCP server for Obsidian. Solves stdio transport failures (BrokenPipeError) affecting Claude Code CLI. HTTP bypasses these issues entirely.
Fast & efficient: <200ms response, 70% fewer API calls, MCP-optimized for minimal token usage
---
Claude Code controlling an Obsidian vault via HTTP-native MCP - no stdio bugs, just seamless AI-powered note management
---
- What Makes This Different?
- Quick Start
- Your Obsidian, Powered by AI
- Updating
- Command Line Options
- Troubleshooting
✅ HTTP that works - No stdio crashes, no BrokenPipeError, no frustration
⏱️ Lightning fast - Create, find, edit, and move notes instantly - even with typos
🛡️ Never lose data - Built-in protection against accidental deletions
⚙️ Set up in 1 minute - No complex configuration, works out of the box
💪 Built for real use - Handles thousands of notes without slowdowns
💸 Token-conscious - Intelligent design minimizes AI usage costs
---
> 💡 New to the codebase? Ask an AI assistant to guide you: "Based on README.md and TECHNICAL.md, walk me through how the HTTP-native MCP server works"
1. Obsidian with Local REST API plugin
2. Node.js 18+ - Download here
3. MCP-compatible AI (e.g., Claude Code CLI, Claude Desktop, Codex, etc.)
#### STEP 1: Configure Obsidian Plugin
- Settings → Community Plugins → Search "Local REST API" → Enable
- Enable "Non encrypted (HTTP) API"
- Copy the API key (you'll need it next)
---
#### STEP 2: Install & Setup
Install where Obsidian is installed:
``bash`
npm install -g obsidian-http-mcp
obsidian-http-mcp --setupEnter your Obsidian API key when prompted
Press Enter to accept defaults for URL and port
Config saved to ~/.obsidian-mcp/config.json - you won't need to type this again.
> Cross-platform users: If your AI runs on WSL2 but Obsidian on Windows, install the server on Windows.
---
#### STEP 3: Start Server
Where you installed (same system as Obsidian):
`bash`
obsidian-http-mcp
⚠️ Keep this terminal running. After reboot, run obsidian-http-mcp again.
---
#### STEP 4: Connect Your AI
If your AI runs where the server is installed:
`bash`
claude mcp add -s user --transport http obsidian-http http://localhost:3000/mcp # Adapt command to your AI
If your AI runs elsewhere (e.g., Claude on WSL2, server on Windows):
1. Find server's IP address on the system where the server runs:
`powershellWindows PowerShell
ipconfig | findstr "vEthernet"
1. Connect from where your AI runs:
bash
claude mcp add -s user --transport http obsidian-http http://SERVER_IP:3000/mcp # Adapt command to your AI
`---
#### STEP 5: Use with Your AI
Run where your AI is installed (Windows, Linux, or WSL2):
bash
claude # Or your AI CLI command
Try: "List all folders in my Obsidian vault"
`That's it! Your AI will automatically connect to the server every time you start a conversation (as long as the server is running).
---
🔄 Updating
To update to the latest version:
bash
npm install -g obsidian-http-mcp@latest
`After updating, restart the server:
bash
obsidian-http-mcp
`---
✨ Your Obsidian, Powered by AI
No more switching between AI and Obsidian - Control your vault directly from your AI assistant
Never lose data - Soft delete protects against accidental AI operations (files moved to
by default)Work at AI speed - Fuzzy search finds files even with typos, intelligent cache reduces API calls by 70%
Scale confidently - Handles 1000+ notes without breaking a sweat (<200ms response time)
What You Can Do:
- Read, write, and edit notes seamlessly without leaving your AI conversation
- Find any file instantly with fuzzy matching ("meeting notes" finds "Meeting-Notes-2024.md")
- Search across thousands of notes in seconds with full regex support
- Move, rename, or delete files with built-in safety features
See TECHNICAL.md for complete tool specifications and architecture details.
---
📖 Command Line Options
`bash
obsidian-http-mcp --helpOptions:
--setup Interactive setup (saves to ~/.obsidian-mcp/config.json)
--api-key Obsidian REST API key (overrides config)
--base-url Obsidian REST API URL (default: http://127.0.0.1:27123)
--port Server port (default: 3000)
--help, -h Show help
--version, -v Show version
Config Priority:
1. CLI arguments (--api-key, --base-url, --port)
2. Environment variables (OBSIDIAN_API_KEY, OBSIDIAN_BASE_URL, PORT)
3. Config file (~/.obsidian-mcp/config.json)
4. .env file
`Alternative: Using .env file (on same system as Obsidian):
1. Create
with OBSIDIAN_API_KEY=your_key
2. Run: (Windows PowerShell or Linux terminal)---
🔧 Troubleshooting
$3
Find your Windows bridge IP:
On Windows PowerShell (not WSL2):
`powershell
ipconfig | findstr "IPv4"
Look for "vEthernet (WSL)" interface
Example output: IPv4 Address. . . . . . . . . . . : 172.19.32.1
`Then reconnect from WSL2 terminal:
bash
claude mcp add -s user --transport http obsidian-http http://YOUR_IP:3000/mcp
Replace YOUR_IP with the IP from above
`> Why not
directly? Port 27123 is Obsidian's REST API (custom HTTP protocol). Port 3000 is the MCP Server that translates between MCP protocol (used by your AI) and Obsidian's REST API. They are different protocols - the MCP server acts as a translator/proxy.$3
Run on Windows PowerShell as Administrator:
`powershell
New-NetFirewallRule -DisplayName "MCP Server" -Direction Inbound -LocalPort 3000 -Protocol TCP -Action Allow
`$3
Run on the same system as Obsidian (Windows PowerShell or Linux terminal):
bash
obsidian-http-mcp --api-key YOUR_KEY --port 3001
`Need more help? See TROUBLESHOOTING.md for detailed troubleshooting and TECHNICAL.md for network architecture.
---
⚠️ Security Notice
Designed for trusted networks (localhost, LAN, VPN). For production deployment:
- Use reverse proxy (nginx/caddy) with authentication
- Enable HTTPS/TLS
- Configure rate limiting
- See SECURITY.md for full checklist
Current state: Binds to
---
See CONTRIBUTING.md for development setup and guidelines.
---
MIT - See LICENSE
---
If this project helps you, please star it on GitHub!
---
- Obsidian Local REST API
- Model Context Protocol
- Claude Code CLI
---
Built with ❤️ for the Obsidian + AI community