Obsidian MCP (Model Context Protocol) Server

English | Chinese

This project implements a Model Context Protocol (MCP) server for connecting AI models with the Obsidian knowledge base. Through this server, AI models can directly access and manipulate Obsidian notes, including reading, creating, updating, and deleting notes, as well as managing folder structures.

Features

• Seamless integration with the Obsidian knowledge base
• Support for reading, creating, updating, and deleting notes
• Support for creating, renaming, moving, and deleting folders
• Full-text search support
• Compliance with the Model Context Protocol specification

Prerequisites

• Node.js (v16 or higher)
• Obsidian desktop application
• Obsidian Local REST API plugin (needs to be installed in Obsidian)

Installation

1. Clone this repository:

bash
git clone https://github.com/newtype-01/obsidian-mcp.git
cd obsidian-mcp

1. Install dependencies:

bash
npm install

1. Build the project:

bash
npm run build

Configuration

The server is configured via environment variables:

• OBSIDIAN_VAULT_PATH: Path to the Obsidian vault
• OBSIDIAN_API_TOKEN: API token for the Obsidian Local REST API plugin
• OBSIDIAN_API_PORT: Port number for the Obsidian Local REST API plugin (default is 27123)

You can set the environment variables as follows:

1. Copy the .env.example file to .env and edit the values:

bash
cp .env.example .env

1. Edit the .env file and fill in your actual configuration:

OBSIDIAN_VAULT_PATH=/path/to/your/vault
OBSIDIAN_API_TOKEN=your_api_token_here
OBSIDIAN_API_PORT=27123

Note: The .env file contains sensitive information and has been added to .gitignore, so it will not be committed to version control.

Usage

Direct Usage

1. Ensure that Obsidian is running and the Local REST API plugin is installed and configured

2. Start the MCP server:

bash
npm start

1. The server will communicate with the AI model via standard input/output

Deployment with Docker

Using Docker Compose (Recommended)

1. Ensure Docker and Docker Compose are installed

2. Copy and configure the environment file:

bash
cp .env.example .env

1. Edit the .env file and fill in your actual configuration:

OBSIDIAN_VAULT_PATH=/path/to/your/vault
OBSIDIAN_API_TOKEN=your_api_token_here
OBSIDIAN_API_PORT=27123

1. Build and start the container:

bash
docker-compose up -d

Using Docker Command

1. Build the Docker image:

bash
docker build -t obsidian-mcp .

1. Run the container:

bash
docker run -d
--name obsidian-mcp
--env-file .env
--network host
-v $(OBSIDIAN_VAULT_PATH):$(OBSIDIAN_VAULT_PATH)
obsidian-mcp

Note: When deploying with Docker, the Docker container needs to access the Obsidian instance and vault on the host. Ensure that the correct paths and ports are set in the .env file, and use network_mode: "host" or appropriate port mapping.

Configuring in MCP Client

Mainstream MCP clients typically require editing the configuration file to set up the MCP server. Here are some common ways to configure:

Using npx Method

json
{
"mcpServers": {
"obsidian-mcp": {
"command": "npx",
"args": [
"obsidian-mcp"
],
"env": {
// If you have already set up the .env file in the project directory, you can leave it empty
// Or you can set the environment variables directly here:
// "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
// "OBSIDIAN_API_TOKEN": "your_api_token_here",
// "OBSIDIAN_API_PORT": "27123"
}
}
}
}

Using Local Installation Method

json
{
"mcpServers": {
"obsidian-mcp": {
"command": "node",
"args": [
"/path/to/obsidian-mcp/build/index.js"
],
"env": {
// If you have already set up the .env file in the project directory, you can leave it empty
}
}
}
}

Using Docker Method

If you have already deployed the MCP server using Docker, you can configure the MCP client as follows:

json
{
"mcpServers": {
"obsidian-mcp": {
"command": "docker",
"args": [
"exec",
"-i",
"obsidian-mcp",
"npm",
"start"
],
"env": {
// The Docker container is already configured via the .env file or environment variables, so you can leave it empty here
}
}
}
}Note: The env section in the above configuration can be left empty, especially if you have already configured the relevant parameters through a .env file or Docker environment variables. If you wish to specify environment variables directly within the client configuration, you can fill in the corresponding key-value pairs in the env section.

Testing

The project includes a test script for verifying server functionality:

bash
node test-mcp.js

Supported Tools

MCP Server provides the following tools:

• list_notes: List all notes in the knowledge base
• read_note: Read the content of a specified note
• create_note: Create a new note
• update_note: Update an existing note
• search_vault: Search for content within the knowledge base
• delete_note: Delete a note
• manage_folder: Manage folders (create, rename, move, delete)

Development

• Run the server in development mode using npm run dev
• Source code is located in the src directory

License

ISC

Contributions

Pull Requests and Issues are welcome!

Related Projects

• Model Context Protocol
• Obsidian Local REST API