
A Model Context Protocol (MCP) server for interacting with Obsidian via its Local REST API.
A Model Context Protocol (MCP) server for interacting with Obsidian via its Local REST API.
·
A Model Context Protocol (MCP) server for interacting with Obsidian via its Local REST API.
Clone this repository:
git clone https://github.com/beshkenadze/mcp-obsidian.git
cd mcp-obsidianInstall dependencies:
make install
# or
bun installGenerate TypeScript types from the OpenAPI spec:
make generate-types
# or
bun run generate-typesYou can install the package directly from npm:
# Install from npm (no authentication required)
npm install @beshkenadze/mcp-obsidian
# or
yarn add @beshkenadze/mcp-obsidian
# or
bun add @beshkenadze/mcp-obsidianAlternatively, you can install from GitHub Packages (requires GitHub authentication):
# Add to .npmrc
@beshkenadze:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
# Then install
npm install @beshkenadze/mcp-obsidian
# or
yarn add @beshkenadze/mcp-obsidian
# or
bun add @beshkenadze/mcp-obsidianThis project uses semantic-release to automate version management and package publishing. The workflow:
Commits must follow the Conventional Commits format
feat: add new feature - triggers a minor releasefix: resolve bug - triggers a patch releasefeat!: or fix!: or refactor!: etc. - triggers a major releasechore:, docs:, style:, refactor:, perf:, test: - no release triggeredWhen commits are pushed to the main branch, the release workflow:
You can also manually trigger a release using the GitHub Actions workflow dispatch.
The MCP server is configured using environment variables:
PORT: The port on which the MCP server will listen (default: 3000)OBSIDIAN_BASE_URL: The URL of the Obsidian Local REST API (default: https://127.0.0.1:27124)OBSIDIAN_API_KEY: Your Obsidian Local REST API key (required)SERVER_TYPE: The server implementation to use - either 'bun' or 'express' (default: 'bun')You can set these variables in a .env file at the root of the project:
PORT=3000
OBSIDIAN_BASE_URL=https://127.0.0.1:27124
OBSIDIAN_API_KEY=your_api_key_here
SERVER_TYPE=bun # Options: bun, expressYou can run the MCP Obsidian server using Docker with different transport modes.
Build the Docker image using the provided Dockerfile:
docker build -t mcp-obsidian .Run the Docker container with the appropriate environment variables:
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=your_api_key_here \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
beshkenadze/mcp-obsidianNote: Use host.docker.internal instead of 127.0.0.1 to access Obsidian running on your host machine from within the Docker container.
The Docker image supports different transport modes:
The default mode serves the MCP server over HTTP:
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=your_api_key_here \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
beshkenadze/mcp-obsidianTo run with SSE transport:
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=your_api_key_here \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=sse \
beshkenadze/mcp-obsidianTo run with stdio transport (useful for integration with other MCP clients):
docker run -i \
-e OBSIDIAN_API_KEY=your_api_key_here \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=stdio \
beshkenadze/mcp-obsidianNote: When using stdio mode, you must run the container with the -i flag to enable interactive mode.
To use the Docker container with Supergateway:
# Pull the public Docker image (no authentication required)
docker pull beshkenadze/mcp-obsidian
# Run the MCP server with stdio transport
docker run -i \
-e OBSIDIAN_API_KEY=your_api_key_here \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=stdio \
beshkenadze/mcp-obsidian | \
npx -y @supercorp/supergatewayThis pipes the stdio output from the Docker container to Supergateway.
Start the MCP server:
make start
# or
bun run startThe server will be available at http://localhost:3000 (or the port you configured).
This MCP server supports two different server implementations:
You can switch between implementations by setting the SERVER_TYPE environment variable:
# For Bun server (default)
SERVER_TYPE=bun bun run start
# For Express server
SERVER_TYPE=express bun run startBoth implementations provide identical functionality and API endpoints. The dual implementation approach allows for:
Run the unit tests:
make test
# or
bun run testRun all tests including integration tests:
make test-all
# or
bun run test:allRun only integration tests (requires a running Obsidian instance with Local REST API):
make test-integration
# or
bun run test:integrationThe test suite includes:
Note: The application automatically handles the self-signed certificate that Obsidian's Local REST API uses by disabling SSL certificate validation. This is secure for local development but should be used with caution if exposing the API to external networks.
This project uses oxlint, a fast Rust-based JavaScript/TypeScript linter.
Run the linter to check for issues:
make lint
# or
bun run lintFix automatically fixable issues:
make lint-fix
# or
bun run lint:fixThe MCP server exposes the following tools:
obsidian_get_status: Get status information from Obsidianobsidian_get_active_file: Get content of the currently active file in Obsidianobsidian_update_active_file: Update the content of the currently active file in Obsidianobsidian_append_to_active_file: Append content to the currently active file in Obsidianobsidian_patch_active_file: Modify the active file relative to headings, blocks, or frontmatterobsidian_delete_active_file: Delete the currently active file in Obsidianobsidian_list_files: List files in a directoryobsidian_get_file: Get content of a fileobsidian_create_or_update_file: Create a new file or update an existing oneobsidian_append_to_file: Append content to a fileobsidian_patch_file: Modify a file relative to headings, blocks, or frontmatterobsidian_delete_file: Delete a fileobsidian_get_periodic_note: Get current periodic note for the specified periodobsidian_update_periodic_note: Update the content of a periodic noteobsidian_append_to_periodic_note: Append content to a periodic noteobsidian_delete_periodic_note: Delete a periodic noteobsidian_patch_periodic_note: Modify a periodic note relative to headings, blocks, or frontmatterobsidian_search: Search for content in vault with simple text queriesobsidian_advanced_search: Advanced search using JsonLogic or Dataview queriesobsidian_open_document: Open a document in Obsidianobsidian_list_commands: List available commands in Obsidianobsidian_execute_command: Execute a command in ObsidianThis MCP server supports Server-Sent Events (SSE) for real-time communication with web clients. There are multiple ways to run the server with SSE support:
Run the server with the SSE transport:
make start-sse
# or
bun run start:sse
# or with Docker
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=your_api_key_here \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=sse \
beshkenadze/mcp-obsidianThis uses Supergateway for SSE implementation and listens on the configured port.
You can also run the server with the dedicated supergateway script:
# Run with supergateway
bun run start:supergateway
# or with Docker
docker run -p 3000:3000 \
-e OBSIDIAN_API_KEY=your_api_key_here \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=stdio \
beshkenadze/mcp-obsidianBoth options provide:
http://localhost:3000/ssehttp://localhost:3000/messagehttp://localhost:3000/healthzTo build a production version:
make build
# or
bun run buildThis will create a build in the dist directory.
For convenience, this project includes a Makefile with the following commands:
make install - Install dependenciesmake build - Build the projectmake lint - Run lintermake lint-fix - Run linter with autofixmake test - Run unit testsmake test-all - Run all testsmake test-integration - Run integration testsmake generate-types - Generate TypeScript typesmake start - Start the applicationmake start-sse - Start the application with SSE transportmake precommit - Run precommit checksmake clean - Clean build artifactsmake docker-build - Build Docker imagemake docker-run - Run Docker container (HTTP mode)make docker-run-sse - Run Docker container with SSE transportmake docker-run-stdio - Run Docker container with stdio transportmake docker-run-supergateway - Run Docker container with supergatewaymake act-build - Test build GitHub Action locallymake act-lint - Test lint GitHub Action locallymake act-test - Test test GitHub Action locallymake act-release-dry - Test release GitHub Action locally (dry run)make act-release - Test release GitHub Action locallymake help - Display help information about available commandsThis package follows the Model Context Protocol server standard and can be used with any MCP client.
You can use this package directly from npm without authentication:
npx @beshkenadze/mcp-obsidianThe recommended way to use this MCP server without authentication is via Docker:
# Pull the public Docker image (no authentication required)
docker pull beshkenadze/mcp-obsidian
# Run with stdio transport for MCP client integration
docker run -i \
-e OBSIDIAN_API_KEY=your_api_key_here \
-e OBSIDIAN_BASE_URL=https://host.docker.internal:27124 \
-e TRANSPORT_TYPE=stdio \
beshkenadze/mcp-obsidianThis method requires no GitHub authentication and works out of the box with any MCP client.
To use this MCP server anonymously:
Since this package is also hosted on GitHub's package registry, you can use it from there with authentication:
Create or update your ~/.npmrc file with your GitHub authentication:
@beshkenadze:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKENYou'll need a GitHub personal access token with the read:packages scope.
Then run:
npx @beshkenadze/mcp-obsidianTo use this MCP server with Claude Desktop, add it to your Claude Desktop configuration:
This method doesn't require GitHub authentication:
{
"mcpServers": {
"obsidian": {
"command": "docker",
"args": ["run", "-i", "beshkenadze/mcp-obsidian"],
"env": {
"OBSIDIAN_API_KEY": "your_api_key_here",
"OBSIDIAN_BASE_URL": "https://host.docker.internal:27124",
"TRANSPORT_TYPE": "stdio"
}
}
}
}This method requires GitHub authentication:
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["@beshkenadze/mcp-obsidian"],
"env": {
"OBSIDIAN_API_KEY": "your_api_key_here",
"NPM_CONFIG_REGISTRY": "https://registry.npmjs.org",
"NPM_CONFIG__AUTH_TYPES": "legacy",
"NPM_CONFIG__AUTHTOKEN": "YOUR_GITHUB_TOKEN",
"NPM_CONFIG__REGISTRY_SCOPES": "@beshkenadze",
"NPM_CONFIG__REGISTRIES_@BESHKENADZE": "https://npm.pkg.github.com"
}
}
}
}Many MCP clients like Continue, Cursor, LibreChat, and others support MCP servers. Refer to your client's documentation for specific configuration details.
If you want to install the package locally (requires GitHub authentication):
# Add to .npmrc
@beshkenadze:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
# Then install
npm install @beshkenadze/mcp-obsidian
# or
yarn add @beshkenadze/mcp-obsidian
# or
bun add @beshkenadze/mcp-obsidianNote: For anonymous access without GitHub authentication, use the Docker method described above.
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add obsidian -- docker run -i beshkenadze/mcp-obsidian{
"mcpServers": {
"obsidian": {
"env": {
"TRANSPORT_TYPE": "",
"OBSIDIAN_API_KEY": "",
"OBSIDIAN_BASE_URL": ""
},
"args": [
"run",
"-i",
"beshkenadze/mcp-obsidian"
],
"command": "docker"
}
}
}code --add-mcp '{"name":"obsidian","env":{"TRANSPORT_TYPE":"","OBSIDIAN_API_KEY":"","OBSIDIAN_BASE_URL":""},"args":["run","-i","beshkenadze/mcp-obsidian"],"command":"docker"}'[mcp_servers.obsidian]
command = "docker"
args = ["run", "-i", "beshkenadze/mcp-obsidian"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/mcp-obsidian to learn what the "MCP Obsidian" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
docker run -p 3000:3000
docker run -inpx -y @supercorp/supergateway
npx @beshkenadze/mcp-obsidianThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: its npm package has not answered in our offline sandbox, which usually means it needs an API key or other configuration to start. The four checks that need a live server are left out, and the grade tops out at B until we can read its tools.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/mcp-obsidian)Nothing comparable is listed yet.
v1.2.0Release notesv1.1.4Release notesv1.0.1Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "mcp-obsidian" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.