MCP Obsidian

A Model Context Protocol (MCP) server for interacting with Obsidian via its Local REST API.

Prerequisites

• Bun runtime
• Obsidian with the Local REST API plugin installed and configured

Installation

1. Clone this repository:

   git clone https://github.com/beshkenadze/mcp-obsidian.git
   cd mcp-obsidian

2. Install dependencies:

   make install
   # or
   bun install

3. Generate TypeScript types from the OpenAPI spec:

   make generate-types
   # or
   bun run generate-types

Installing as a Package

You 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-obsidian

Alternatively, 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-obsidian

Development

Release Process

This project uses semantic-release to automate version management and package publishing. The workflow:

1. Commits must follow the Conventional Commits format

   • feat: add new feature - triggers a minor release
   • fix: resolve bug - triggers a patch release
   • feat!: or fix!: or refactor!: etc. - triggers a major release
   • chore:, docs:, style:, refactor:, perf:, test: - no release triggered

2. When commits are pushed to the main branch, the release workflow:

   • Determines the next version number based on commit messages
   • Updates package.json with the new version
   • Generates release notes from commits
   • Creates a GitHub release with the notes
   • Publishes to both npm Registry and GitHub Packages
   • Updates the repository with version changes

You can also manually trigger a release using the GitHub Actions workflow dispatch.

Configuration

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, express

Docker Support

You can run the MCP Obsidian server using Docker with different transport modes.

Building the Docker Image

Build the Docker image using the provided Dockerfile:

docker build -t mcp-obsidian .

Running with Docker

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-obsidian

Note: Use host.docker.internal instead of 127.0.0.1 to access Obsidian running on your host machine from within the Docker container.

Available Transport Modes

The Docker image supports different transport modes:

1. HTTP Mode (Default)

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-obsidian

2. SSE Mode

To 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-obsidian

3. stdio Mode

To 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-obsidian

Note: When using stdio mode, you must run the container with the -i flag to enable interactive mode.

Using Docker with Supergateway

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/supergateway

This pipes the stdio output from the Docker container to Supergateway.

Usage

Running the MCP Server

Start the MCP server:

make start
# or
bun run start

The server will be available at http://localhost:3000 (or the port you configured).

Server Implementation

This MCP server supports two different server implementations:

1. Bun Server (default): Uses Bun's native HTTP server implementation for optimal performance in Bun environments.
2. Express Server: Uses Express.js for compatibility with Node.js environments and broader ecosystem support.

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 start

Both implementations provide identical functionality and API endpoints. The dual implementation approach allows for:

• Testing in different environments
• Compatibility with both Bun and Node.js deployments
• Performance comparison between different server architectures

Testing

Run the unit tests:

make test
# or
bun run test

Run all tests including integration tests:

make test-all
# or
bun run test:all

Run only integration tests (requires a running Obsidian instance with Local REST API):

make test-integration
# or
bun run test:integration

The test suite includes:

• Unit tests with mocks for the ObsidianClient and McpServer components
• Integration tests that test the actual communication with Obsidian

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.

Linting

This project uses oxlint, a fast Rust-based JavaScript/TypeScript linter.

Run the linter to check for issues:

make lint
# or
bun run lint

Fix automatically fixable issues:

make lint-fix
# or
bun run lint:fix

Available MCP Tools

The MCP server exposes the following tools:

• obsidian_get_status: Get status information from Obsidian
• obsidian_get_active_file: Get content of the currently active file in Obsidian
• obsidian_update_active_file: Update the content of the currently active file in Obsidian
• obsidian_append_to_active_file: Append content to the currently active file in Obsidian
• obsidian_patch_active_file: Modify the active file relative to headings, blocks, or frontmatter
• obsidian_delete_active_file: Delete the currently active file in Obsidian
• obsidian_list_files: List files in a directory
• obsidian_get_file: Get content of a file
• obsidian_create_or_update_file: Create a new file or update an existing one
• obsidian_append_to_file: Append content to a file
• obsidian_patch_file: Modify a file relative to headings, blocks, or frontmatter
• obsidian_delete_file: Delete a file
• obsidian_get_periodic_note: Get current periodic note for the specified period
• obsidian_update_periodic_note: Update the content of a periodic note
• obsidian_append_to_periodic_note: Append content to a periodic note
• obsidian_delete_periodic_note: Delete a periodic note
• obsidian_patch_periodic_note: Modify a periodic note relative to headings, blocks, or frontmatter
• obsidian_search: Search for content in vault with simple text queries
• obsidian_advanced_search: Advanced search using JsonLogic or Dataview queries
• obsidian_open_document: Open a document in Obsidian
• obsidian_list_commands: List available commands in Obsidian
• obsidian_execute_command: Execute a command in Obsidian

Running with SSE Support

This 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:

1. Using Built-in SSE Mode

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-obsidian

This uses Supergateway for SSE implementation and listens on the configured port.

2. Using Supergateway Directly

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-obsidian

Both options provide:

• SSE endpoint at: http://localhost:3000/sse
• Message endpoint at: http://localhost:3000/message
• CORS support for cross-origin requests
• Health endpoint at: http://localhost:3000/healthz
• Improved compatibility with various MCP clients

Building for Production

To build a production version:

make build
# or
bun run build

This will create a build in the dist directory.

Available Makefile Commands

For convenience, this project includes a Makefile with the following commands:

• make install - Install dependencies
• make build - Build the project
• make lint - Run linter
• make lint-fix - Run linter with autofix
• make test - Run unit tests
• make test-all - Run all tests
• make test-integration - Run integration tests
• make generate-types - Generate TypeScript types
• make start - Start the application
• make start-sse - Start the application with SSE transport
• make precommit - Run precommit checks
• make clean - Clean build artifacts
• make docker-build - Build Docker image
• make docker-run - Run Docker container (HTTP mode)
• make docker-run-sse - Run Docker container with SSE transport
• make docker-run-stdio - Run Docker container with stdio transport
• make docker-run-supergateway - Run Docker container with supergateway
• make act-build - Test build GitHub Action locally
• make act-lint - Test lint GitHub Action locally
• make act-test - Test test GitHub Action locally
• make act-release-dry - Test release GitHub Action locally (dry run)
• make act-release - Test release GitHub Action locally
• make help - Display help information about available commands

Using as an MCP Server

This package follows the Model Context Protocol server standard and can be used with any MCP client.

Using with npx (npm Registry - No Authentication Required)

You can use this package directly from npm without authentication:

npx @beshkenadze/mcp-obsidian

Using with Docker (Recommended for Anonymous Access)

The 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-obsidian

This method requires no GitHub authentication and works out of the box with any MCP client.

Setting Up Anonymous Access

To use this MCP server anonymously:

1. Use npm directly: The package is available on the npm registry without authentication requirements.
2. Use the Docker approach: The Docker image is publicly available without authentication requirements.
3. No GitHub tokens or authentication needed.
4. The only authentication you'll need is your Obsidian API key, which is for Obsidian access, not package access.

Using with npx (GitHub Packages - Requires Authentication)

Since this package is also hosted on GitHub's package registry, you can use it from there with authentication:

1. Create or update your ~/.npmrc file with your GitHub authentication:

   @beshkenadze:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

   You'll need a GitHub personal access token with the read:packages scope.

2. Then run:

   npx @beshkenadze/mcp-obsidian

Configuring in Claude Desktop

To use this MCP server with Claude Desktop, add it to your Claude Desktop configuration:

Option 1: Using Docker (Recommended for Anonymous Access)

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"
      }
    }
  }
}

Option 2: Using npx with GitHub authentication

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"
      }
    }
  }
}

Configuring in Other MCP Clients

Many MCP clients like Continue, Cursor, LibreChat, and others support MCP servers. Refer to your client's documentation for specific configuration details.

Installation as a Package

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-obsidian

Note: For anonymous access without GitHub authentication, use the Docker method described above.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.