docker-mcp-obsidian

# Docker MCP Obsidian https://github.com/user-attachments/assets/a8d88633-0ace-432e-a1e4-4e0be10ac688 A Docker container setup for running Obsidian with MCP (Model Context Protocol) support. ## Overview This project provides a containerized Obsidian instance that can be used as an MCP server, allowing MCP clients to interact with Obsidian notes and functionality through the Model Context Protocol. ## Components - **Dockerfile**: Based on `lscr.io/linuxserver/obsidian:latest` with `uv` package manager installed - **build.sh**: Script to build the Docker image - **run.sh**: Script to run the Docker container with proper configuration - **mcp-entry-sample.json**: Sample MCP client configuration for connecting to the running container - **vault/**: Directory containing Obsidian vault data (includes Local REST API plugin configuration) ## Prerequisites - Docker installed and running on your system - Basic familiarity with Docker commands - An MCP client that supports the Model Context Protocol > **Note**: This project relies on two key components: > 1. **[Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api)** - An Obsidian plugin that provides a REST API for interacting with notes. This is pre-configured in the vault with API key authentication. > 2. **[mcp-obsidian](https://github.com/calclavia/mcp-obsidian)** - A Model Context Protocol server that connects to the Local REST API, allowing MCP clients to interact with Obsidian notes. ## Quick Start ### 1. Build the Docker Image Run the build script to create the Docker image: ```bash ./build.sh ``` This script will: - Build a Docker image tagged as `mcp-obsidian:latest` - Install the `uv` package manager for Python dependencies ### 2. Run the Container Start the Obsidian container using the run script: ```bash ./run.sh ``` This script will: - Remove any existing container named `mcp-obsidian` - Start a new container with the following configuration: - **Name**: `mcp-obsidian` - **Port**: 3000 (mapped to host port 3000) - **Vault**: `./vault` directory mounted to `/vault` in container - **Environment Variables**: - `PUID=1000` and `PGID=1000` (user/group IDs) - `TZ=America/Los_Angeles` (timezone) - `OBSIDIAN_API_KEY`: Pre-configured API key for MCP access - `OBSIDIAN_HOST=127.0.0.1` and `OBSIDIAN_PORT=27123` - **Restart Policy**: `unless-stopped` ### 3. Access Obsidian Once the container is running, you can access Obsidian through your web browser at: ``` http://localhost:3000 ``` ## MCP Client Connection ### Using the Sample Configuration The `mcp-entry-sample.json` file provides a sample configuration entry for MCP clients to connect to the running Obsidian container. This should be added to your MCP client's configuration file: ```json "mcp-obsidian": { "command": "docker", "args": [ "exec", "-i", "mcp-obsidian", "uvx", "mcp-obsidian" ] } ``` **Note**: The file contains dots (`....`) at the beginning and end, indicating this is a fragment to be inserted into a larger MCP configuration file. ### How to Use 1. **Ensure the container is running** by executing `./run.sh` 2. **Copy the sample configuration** from `mcp-entry-sample.json` 3. **Add the configuration** to your MCP client's configuration file 4. **Connect** using your MCP client The configuration tells the MCP client to: - Use Docker to execute commands in the `mcp-obsidian` container - Run the `mcp-obsidian` package using `uvx` (uv's execution command) ## Configuration Details > **How it works**: The MCP server (`mcp-obsidian`) communicates with Obsidian through the **Local REST API plugin**, which must be enabled in your Obsidian vault. The vault included in this project comes pre-configured with the plugin and API key authentication. ### Sample system prompt for automatic note taking on conversations > You are a note taker. When I chat with you, you are to make notes out of our conversation. If I ask you a question, check if there exists a note about the topic already in obsidian, answer the question based on your own knowledge and the content from obsidian, and then create or update the note in Obsidian if there is information you used not present in the Obsidian note. Create links between notes whenever possible and keep notes small and atomic. ### Environment Variables | Variable | Value | Description | |----------|-------|-------------| | `PUID` | 1000 | User ID for file permissions | | `PGID` | 1000 | Group ID for file permissions | | `TZ` | America/Los_Angeles | Container timezone | | `OBSIDIAN_API_KEY` | (pre-configured) | API key for Local REST API plugin authentication | | `OBSIDIAN_HOST` | 127.0.0.1 | Host for Local REST API plugin | | `OBSIDIAN_PORT` | 27123 | Port for Local REST API plugin (insecure HTTP) | ### Volumes - `./vault:/vault` - Maps the local `vault` directory to the container's `/vault` directory for persistent storage ### Ports - `3000:3000` - Maps container port 3000 to host port 3000 for web access ## Troubleshooting ### Container Issues - **Check if container is running**: `docker ps | grep mcp-obsidian` - **View container logs**: `docker logs mcp-obsidian` - **Stop container**: `docker stop mcp-obsidian` - **Remove container**: `docker rm mcp-obsidian` ### Permission Issues If you encounter permission issues with the vault directory: ```bash # Ensure proper ownership sudo chown -R 1000:1000 vault/ ``` ## Development To modify the container configuration: 1. Edit the `Dockerfile` for image changes 2. Edit `run.sh` for runtime configuration changes 3. Rebuild with `./build.sh` after Dockerfile changes 4. Restart with `./run.sh` after runtime configuration changes