We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/OleksandrKucherenko/mcp-obsidian-via-rest'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>MCP Obsidian Server - How to Run</title>
<!-- Twitter Card metadata -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="MCP Obsidian Server - How to Run">
<meta name="twitter:description" content="Quick setup guide for running the MCP Obsidian server">
<meta name="twitter:image" content="https://raw.githubusercontent.com/OleksandrKucherenko/mcp-obsidian-via-rest/main/docs/obsidian-logo-bw.webp">
<meta name="twitter:site" content="@OKucherenko">
<!-- Simple CSS framework from CDN -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/water.css@2/out/water.css">
<!-- Syntax highlighting -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-okaidia.min.css">
<style>
:root {
--primary-color: #7e57c2;
}
body {
max-width: 900px;
margin: 0 auto;
padding: 1rem;
}
header {
margin-bottom: 2rem;
text-align: center;
border-bottom: 2px solid var(--primary-color);
padding-bottom: 1rem;
}
.badges {
display: flex;
justify-content: center;
gap: 10px;
margin: 1rem 0;
}
.container {
margin-bottom: 2rem;
}
img {
max-width: 100%;
display: block;
margin: 1rem auto;
border: 1px solid #ccc;
border-radius: 5px;
}
.step {
margin-bottom: 1.5rem;
padding: 1rem;
border-left: 3px solid var(--primary-color);
background-color: rgba(126, 87, 194, 0.05);
}
.note {
background-color: rgba(54, 53, 45, 0.8);
padding: 0.8rem;
border-left: 3px solid #ffb74d;
margin: 1rem 0;
}
footer {
margin-top: 3rem;
text-align: center;
font-size: 0.9rem;
}
.rounded {
border: none;
}
.screenshot-link {
color: var(--primary-color);
text-decoration: none;
font-weight: 500;
}
.screenshot-link:hover {
text-decoration: underline;
}
.screenshot-date {
color: #666;
font-size: 0.9rem;
margin: 0.5rem 0;
}
</style>
</head>
<body>
<header>
<div class="logo">
<img src="./obsidian-logo-bw.webp" alt="Obsidian Logo" width="120px" class="rounded">
</div>
<h1>MCP Obsidian Server</h1>
<p>Quick setup guide for running the MCP Obsidian server</p>
<div class="badges">
<!--
[](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/npm-npmjs.yml)
-->
<a href="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/npm-npmjs.yml">
<img src="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/npm-npmjs.yml/badge.svg" alt="NPM">
</a>
<!--
[](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/npm-github.yml)
-->
<a href="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/npm-github.yml">
<img src="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/npm-github.yml/badge.svg" alt="NPM GitHub">
</a>
<!--
[](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/docker-github.yml)
-->
<a href="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/docker-github.yml">
<img src=" https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/docker-github.yml/badge.svg" alt="Docker GitHub">
</a>
<!--
[](https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/docker-hub.yml)
-->
<a href="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/docker-hub.yml" class="badge-link">
<img src="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/actions/workflows/docker-hub.yml/badge.svg" alt="Docker (Docker Hub)">
</a>
<!-- Wiki -->
<a href="https://deepwiki.com/OleksandrKucherenko/mcp-obsidian-via-rest" class="badge-link">
<img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">
</a>
</div>
</header>
<div class="container">
<h2>Latest Screenshots</h2>
<div class="step" id="screenshots-section">
<p>Loading screenshots...</p>
</div>
</div>
<div class="container">
<h2>Step 1: Set Up Obsidian</h2>
<div class="step">
<p>Install and run <a href="https://obsidian.md/" target="_blank">Obsidian Desktop Application</a> and enable the <a href="https://github.com/coddingtonbear/obsidian-local-rest-api" target="_blank">Local REST API</a> plugin in Settings.</p>
<p>Make sure to configure the API to listen on all interfaces (not just localhost), which is critical for WSL2 setup.</p>
<img src="./obsidian-setup.jpg" alt="Obsidian Local REST API Setup">
<p><strong>Important:</strong> Copy the API Key from Obsidian Settings, you'll need it for MCP configuration.</p>
</div>
<h2>Step 2: Configure MCP</h2>
<div class="step">
<p>Create or update your MCP configuration file with one of the following options:</p>
<h3>Option A: Docker (Recommended)</h3>
<pre><code class="language-json">{
"mcpServers": {
"obsidian": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "API_KEY",
"-e", "API_URLS",
"-e", "DEBUG",
"ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"
],
"env": {
"API_KEY": "<your-obsidian-api-key>",
"API_URLS": "[\"https://host.docker.internal:27124\"]",
"DEBUG": "mcp:*"
}
}
}
}</code></pre>
<h3>Option B: NPX/Bunx</h3>
<pre><code class="language-json">{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "@oleksandrkucherenko/mcp-obsidian"],
"env": {
"API_KEY": "<your-obsidian-api-key>",
"API_URLS": "[\"https://127.0.0.1:27124\"]",
"DEBUG": "mcp:*"
}
}
}
}</code></pre>
<div class="note">
<p><strong>Configuration Notes:</strong></p>
<ul>
<li>Replace <code><your-obsidian-api-key></code> with the API Key you copied from Obsidian.</li>
<li><code>API_URLS</code> is a JSON array of URLs. You can specify multiple URLs for automatic failover.</li>
<li>Docker uses <code>host.docker.internal</code> to reach the host machine.</li>
<li>NPX/Bunx runs locally, so use <code>127.0.0.1</code> or <code>localhost</code>.</li>
<li>For WSL2: use <code>["https://127.0.0.1:27124", "https://172.26.32.1:27124"]</code> (replace with your Windows host IP).</li>
<li><code>DEBUG</code> is optional - remove it to disable verbose logging.</li>
</ul>
</div>
</div>
<h2>Step 3: Verify REST API Connection</h2>
<div class="step">
<h3>On Windows:</h3>
<pre><code class="language-bash"># Verify that the port is listening
netstat -an | findstr 27124 # Windows CMD
# Test the API connection
curl --insecure https://localhost:27124</code></pre>
<h3>On WSL2 (Ubuntu):</h3>
<pre><code class="language-bash"># Get Windows host IP
export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}')
echo $WSL_GATEWAY_IP
# Test the API connection
curl --insecure https://$WSL_GATEWAY_IP:27124</code></pre>
<h3>On Linux:</h3>
<pre><code class="language-bash"># check is port is listening
ss -tuln | grep ':27124'
# Test the API connection
wget --no-check-certificate -S https://localhost:27124</code></pre>
<h3>On MacOS:</h3>
<pre><code class="language-bash"># check is port is listening
sudo lsof -iTCP:27124 -sTCP:LISTEN
# Test the API connection (Httpie)
http --verify=no https://localhost:27124</code></pre>
<p>Expected successful response:</p>
<pre><code class="language-json">{
"status": "OK",
"manifest": {
"id": "obsidian-local-rest-api",
"name": "Local REST API",
/* other manifest details... */
},
"service": "Obsidian Local REST API",
"authenticated": false
}</code></pre>
</div>
<h2>Step 4: Check Firewall Settings (Windows)</h2>
<div class="step">
<p>Ensure your firewall allows connections on port 27124:</p>
<pre><code class="language-powershell"># Add firewall rule (Run in Admin PowerShell)
New-NetFirewallRule -DisplayName "WSL2 Obsidian REST API" -Direction Inbound -LocalPort 27124 -Protocol TCP -Action Allow</code></pre>
</div>
<h2>Step 5: Run the MCP Server (without IDE)</h2>
<div class="step">
<p>You can now run the MCP server using Docker:</p>
<pre><code class="language-bash">docker run --name mcp-obsidian-windsurf \
--interactive \
--rm \
-e API_KEY="your-api-key" \
-e API_HOST="https://your-host-ip" \
-e API_PORT="27124" \
-e DEBUG="mcp:*" \
ghcr.io/oleksandrkucherenko/obsidian-mcp:latest</code></pre>
<div class="note">
<p>Docker arguments explained:</p>
<ul>
<li><code>--rm</code> - Automatically remove the container when it exits</li>
<li><code>--interactive</code> - Keep STDIN open</li>
<li><code>-e, --env</code> - Set environment variables</li>
</ul>
</div>
</div>
</div>
<div class="container">
<h2>Step 6: Configure Your AI CLI Tool</h2>
<p>Configure your preferred AI CLI tool to use the MCP Obsidian server. Choose between Docker-hosted or NPX/Bunx-hosted versions.</p>
<h3>Claude Code CLI</h3>
<div class="step">
<p><strong>Docker:</strong></p>
<pre><code class="language-json">{
"mcpServers": {
"obsidian": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS",
"ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"],
"env": {
"API_KEY": "<your-obsidian-api-key>",
"API_URLS": "[\"https://host.docker.internal:27124\"]"
}
}
}
}</code></pre>
<p><strong>NPX/Bunx:</strong></p>
<pre><code class="language-json">{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "@oleksandrkucherenko/mcp-obsidian"],
"env": {
"API_KEY": "<your-obsidian-api-key>",
"API_URLS": "[\"https://127.0.0.1:27124\"]"
}
}
}
}</code></pre>
<p>Save as <code>mcp.json</code> and run: <code>claude --mcp-config ./mcp.json</code></p>
</div>
<h3>Gemini CLI</h3>
<div class="step">
<p><strong>Docker:</strong></p>
<pre><code class="language-bash">gemini mcp add \
-e API_KEY=<your-obsidian-api-key> \
-e API_URLS='["https://host.docker.internal:27124"]' \
obsidian \
docker run --rm -i ghcr.io/oleksandrkucherenko/obsidian-mcp:latest</code></pre>
<p><strong>NPX/Bunx:</strong></p>
<pre><code class="language-bash">gemini mcp add \
-e API_KEY=<your-obsidian-api-key> \
-e API_URLS='["https://127.0.0.1:27124"]' \
obsidian \
npx -y @oleksandrkucherenko/mcp-obsidian</code></pre>
<p><strong>HTTP Transport:</strong> <code>gemini mcp add --transport http obsidian-http http://localhost:3000/mcp</code></p>
</div>
<h3>OpenCode CLI</h3>
<div class="step">
<p>Create <code>opencode.json</code> in your project root:</p>
<p><strong>Docker:</strong></p>
<pre><code class="language-json">{
"mcp": {
"obsidian": {
"type": "local",
"command": ["docker", "run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS",
"ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"],
"environment": {
"API_KEY": "{env:API_KEY}",
"API_URLS": "[\"https://host.docker.internal:27124\"]"
},
"enabled": true
}
}
}</code></pre>
<p><strong>NPX/Bunx:</strong></p>
<pre><code class="language-json">{
"mcp": {
"obsidian": {
"type": "local",
"command": ["npx", "-y", "@oleksandrkucherenko/mcp-obsidian"],
"environment": {
"API_KEY": "{env:API_KEY}",
"API_URLS": "[\"https://127.0.0.1:27124\"]"
},
"enabled": true
}
}
}</code></pre>
</div>
<h3>Kilo Code CLI</h3>
<div class="step">
<p>Create <code>.kilocode/mcp.json</code> in your project:</p>
<p><strong>Docker:</strong></p>
<pre><code class="language-json">{
"mcpServers": {
"obsidian": {
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS",
"ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"],
"env": {
"API_KEY": "<your-obsidian-api-key>",
"API_URLS": "[\"https://host.docker.internal:27124\"]"
}
}
}
}</code></pre>
<p><strong>NPX/Bunx:</strong></p>
<pre><code class="language-json">{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "@oleksandrkucherenko/mcp-obsidian"],
"env": {
"API_KEY": "<your-obsidian-api-key>",
"API_URLS": "[\"https://127.0.0.1:27124\"]"
}
}
}
}</code></pre>
</div>
<h3>Codex CLI</h3>
<div class="step">
<p><strong>Docker:</strong></p>
<pre><code class="language-bash">codex mcp add obsidian \
--command "docker run --rm -i -e API_KEY -e API_URLS ghcr.io/oleksandrkucherenko/obsidian-mcp:latest" \
--env API_KEY=<your-obsidian-api-key> \
--env 'API_URLS=["https://host.docker.internal:27124"]'</code></pre>
<p><strong>NPX/Bunx:</strong></p>
<pre><code class="language-bash">codex mcp add obsidian \
--command "npx -y @oleksandrkucherenko/mcp-obsidian" \
--env API_KEY=<your-obsidian-api-key> \
--env 'API_URLS=["https://127.0.0.1:27124"]'</code></pre>
</div>
<h3>GitHub Copilot CLI</h3>
<div class="step">
<p>Create <code>~/.copilot/mcp-config.json</code> (or <code>.copilot/mcp-config.json</code> in repo root):</p>
<p><strong>Docker:</strong></p>
<pre><code class="language-json">{
"mcpServers": {
"obsidian": {
"type": "local",
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "API_KEY", "-e", "API_URLS",
"ghcr.io/oleksandrkucherenko/obsidian-mcp:latest"],
"env": {
"API_KEY": "${OBSIDIAN_API_KEY}",
"API_URLS": "[\"https://host.docker.internal:27124\"]"
},
"tools": ["*"]
}
}
}</code></pre>
<p><strong>NPX/Bunx:</strong></p>
<pre><code class="language-json">{
"mcpServers": {
"obsidian": {
"type": "local",
"command": "npx",
"args": ["-y", "@oleksandrkucherenko/mcp-obsidian"],
"env": {
"API_KEY": "${OBSIDIAN_API_KEY}",
"API_URLS": "[\"https://127.0.0.1:27124\"]"
},
"tools": ["*"]
}
}
}</code></pre>
<div class="note">
<p>Copilot CLI v0.0.340+ requires <code>${VAR}</code> syntax for env expansion. Set <code>OBSIDIAN_API_KEY</code> in your shell.</p>
</div>
</div>
<h3>Quick Reference</h3>
<div class="step">
<table>
<thead>
<tr>
<th>CLI Tool</th>
<th>Config File</th>
<th>Docker</th>
<th>HTTP</th>
</tr>
</thead>
<tbody>
<tr><td>Claude Code</td><td><code>mcp.json</code></td><td>✅</td><td>✅</td></tr>
<tr><td>Gemini</td><td><code>settings.json</code></td><td>✅</td><td>✅</td></tr>
<tr><td>OpenCode</td><td><code>opencode.json</code></td><td>✅</td><td>✅</td></tr>
<tr><td>Kilo Code</td><td><code>.kilocode/mcp.json</code></td><td>✅</td><td>✅</td></tr>
<tr><td>Codex</td><td>CLI commands</td><td>✅</td><td>✅</td></tr>
<tr><td>Copilot</td><td><code>~/.copilot/mcp-config.json</code></td><td>✅</td><td>✅</td></tr>
</tbody>
</table>
<p>For detailed testing, see <a href="./04_manual_testing.md">Manual Testing Guide</a>.</p>
</div>
</div>
<div class="container">
<h2>Troubleshooting</h2>
<h3>Connectivity Issues</h3>
<div class="step">
<p>To test connectivity from a Docker container:</p>
<pre><code class="language-bash"># Get Windows host IP
export WSL_GATEWAY_IP=$(ip route show | grep -i default | awk '{ print $3}')
echo $WSL_GATEWAY_IP # expected something like: 172.26.32.1
# Run a test container shell
docker run --rm -it --network=host busybox sh
</code></pre>
<p>Inside the container shell:</p>
<pre><code class="language-bash"># Inside the container shell
export WINDOWS_HOST_IP="172.26.32.1" # Replace with your host IP
wget -qO- --no-check-certificate "https://$WINDOWS_HOST_IP:27124"</code></pre>
</div>
<h3>Firewall Issues</h3>
<div class="step">
<p>To temporarily disable Windows Firewall for testing (not recommended for regular use):</p>
<pre><code class="language-powershell"># Run in Admin PowerShell
Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled False
# Remember to re-enable after testing
Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled True</code></pre>
</div>
</div>
<footer>
<p>For more information, visit:</p>
<p>
<a href="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest">GitHub Repository</a> |
<a href="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/tree/main/docs">More Documentation</a> |
<a href="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/pkgs/npm/mcp-obsidian">NPM Package Releases</a> |
<a href="https://github.com/OleksandrKucherenko/mcp-obsidian-via-rest/pkgs/container/obsidian-mcp">Docker Image Releases</a>
</p>
<!--p class="version-info">Version: {{version}} | Commit: {{hash}}</p-->
</footer>
<!-- Scripts for syntax highlighting -->
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-powershell.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-json.min.js"></script>
<!-- Script to load and display screenshots -->
<script>
async function loadScreenshots() {
const section = document.getElementById('screenshots-section');
try {
const response = await fetch('./screenshots.json');
if (!response.ok) throw new Error('Failed to load screenshots');
const data = await response.json();
if (!data.screenshots || data.screenshots.length === 0) {
section.innerHTML = '<p>No screenshots available yet.</p>';
return;
}
const latest = data.screenshots[0];
section.innerHTML = `
<p><a href="./${latest.id}/" class="screenshot-link">
<strong>📸 Latest Screenshots</strong> (Run #${latest.id})
</a></p>
<p class="screenshot-date">Last updated: ${new Date(latest.modified).toLocaleString()}</p>
<p><a href="./screenshots.json" class="screenshot-link">View all screenshots</a></p>
`;
} catch (error) {
console.error('Error loading screenshots:', error);
section.innerHTML = '<p>No screenshots available yet.</p>';
}
}
// Load screenshots on page load
document.addEventListener('DOMContentLoaded', loadScreenshots);
</script>
</body>
</html>