obsidian-mcp-server 1.5.6 → 1.5.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -211
- package/package.json +8 -5
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.typescriptlang.org/)
|
|
4
4
|
[](https://modelcontextprotocol.io/)
|
|
5
|
-
[](https://opensource.org/licenses/Apache-2.0)
|
|
6
6
|
[]()
|
|
7
7
|
[](https://github.com/cyanheads/obsidian-mcp-server)
|
|
8
8
|
|
|
@@ -10,55 +10,51 @@ A Model Context Protocol server designed for LLMs to interact with Obsidian vaul
|
|
|
10
10
|
|
|
11
11
|
The Model Context Protocol (MCP) enables AI models to interact with external tools and resources through a standardized interface.
|
|
12
12
|
|
|
13
|
-
Requires the Local REST API plugin in Obsidian.
|
|
13
|
+
Requires the [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) in Obsidian.
|
|
14
14
|
|
|
15
|
-
##
|
|
15
|
+
## 📋 Table of Contents
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
[Features](#-features) | [Installation](#-installation) | [Configuration](#-configuration) | [Tools](#-tools) | [Resources](#-resources) | [Project Structure](#-project-structure) | [Contributing](#-contributing) | [Publishing](#-publishing) | [License](#-license)
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
- Resource monitoring and cleanup
|
|
21
|
-
- Error handling and graceful failure
|
|
19
|
+
## ✨ Features
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
- **File Operations**: Atomic file/directory operations with validation, resource monitoring, and error handling.
|
|
22
|
+
- **Search System**: Full-text search with configurable context, advanced JsonLogic queries, glob patterns, and frontmatter field support.
|
|
23
|
+
- **Property Management**: YAML frontmatter parsing, intelligent merging, automatic timestamps, and custom field support.
|
|
24
|
+
- **Security & Performance**: API key authentication, rate limiting, SSL options, resource monitoring, and graceful shutdown.
|
|
24
25
|
|
|
25
|
-
|
|
26
|
-
- Advanced JsonLogic queries for files, tags, and metadata
|
|
27
|
-
- Support for glob patterns and frontmatter fields
|
|
26
|
+
## 🚀 Installation
|
|
28
27
|
|
|
29
|
-
|
|
28
|
+
Note: Requires Node.js and the [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) enabled in Obsidian.
|
|
30
29
|
|
|
31
|
-
|
|
32
|
-
- Automatic timestamps (created by Obsidian, modified by server)
|
|
33
|
-
- Custom field support
|
|
30
|
+
### Option 1: Clone and Build (for development or direct use)
|
|
34
31
|
|
|
35
|
-
|
|
32
|
+
1. Enable the Local REST API plugin in Obsidian.
|
|
33
|
+
2. Clone the repository, install dependencies, and build the project:
|
|
34
|
+
```bash
|
|
35
|
+
git clone git@github.com:cyanheads/obsidian-mcp-server.git
|
|
36
|
+
cd obsidian-mcp-server
|
|
37
|
+
npm install
|
|
38
|
+
npm run build
|
|
39
|
+
```
|
|
40
|
+
3. Configure the server using environment variables and run it using `node build/index.js` (see Configuration section below).
|
|
36
41
|
|
|
37
|
-
|
|
38
|
-
- Resource monitoring and health checks
|
|
39
|
-
- Graceful shutdown handling
|
|
42
|
+
### Option 2: Install via npm (as a dependency or globally)
|
|
40
43
|
|
|
41
|
-
|
|
44
|
+
1. Enable the Local REST API plugin in Obsidian.
|
|
45
|
+
2. Install the package using npm:
|
|
42
46
|
|
|
43
|
-
|
|
47
|
+
```bash
|
|
48
|
+
# Install locally (e.g., within another project)
|
|
49
|
+
npm install obsidian-mcp-server
|
|
44
50
|
|
|
45
|
-
|
|
46
|
-
|
|
51
|
+
# Or install globally
|
|
52
|
+
npm install -g obsidian-mcp-server
|
|
53
|
+
```
|
|
47
54
|
|
|
48
|
-
|
|
49
|
-
git clone git@github.com:cyanheads/obsidian-mcp-server.git
|
|
50
|
-
cd obsidian-mcp-server
|
|
51
|
-
npm install
|
|
52
|
-
npm run build
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
Or install from npm:
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
npm install obsidian-mcp-server
|
|
59
|
-
```
|
|
55
|
+
3. Configure the server using environment variables and run it (see Configuration section below).
|
|
60
56
|
|
|
61
|
-
## Configuration
|
|
57
|
+
## ⚙️ Configuration
|
|
62
58
|
|
|
63
59
|
Add to your MCP client settings (e.g., `claude_desktop_config.json` or `cline_mcp_settings.json`):
|
|
64
60
|
|
|
@@ -86,35 +82,42 @@ Add to your MCP client settings (e.g., `claude_desktop_config.json` or `cline_mc
|
|
|
86
82
|
}
|
|
87
83
|
```
|
|
88
84
|
|
|
89
|
-
Environment Variables
|
|
90
|
-
|
|
91
|
-
Required:
|
|
92
|
-
|
|
93
|
-
- `
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
- `
|
|
98
|
-
- `
|
|
99
|
-
- `
|
|
100
|
-
- `
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
85
|
+
**Environment Variables:**
|
|
86
|
+
|
|
87
|
+
- `OBSIDIAN_API_KEY` (Required): Your API key from Obsidian's Local REST API plugin settings.
|
|
88
|
+
- `VERIFY_SSL` (Default: `false`): Enable SSL verification. Set to `false` for self-signed certificates or local use.
|
|
89
|
+
- `OBSIDIAN_PROTOCOL` (Default: `"https"`): Protocol (`http` or `https`).
|
|
90
|
+
- `OBSIDIAN_HOST` (Default: `"127.0.0.1"`): Host address.
|
|
91
|
+
- `OBSIDIAN_PORT` (Default: `27124`): Port number.
|
|
92
|
+
- `REQUEST_TIMEOUT` (Default: `5000`): Request timeout (ms).
|
|
93
|
+
- `MAX_CONTENT_LENGTH` (Default: `52428800` [50MB]): Max response content length (bytes).
|
|
94
|
+
- `MAX_BODY_LENGTH` (Default: `52428800` [50MB]): Max request body length (bytes).
|
|
95
|
+
- `RATE_LIMIT_WINDOW_MS` (Default: `900000` [15 min]): Rate limit window (ms).
|
|
96
|
+
- `RATE_LIMIT_MAX_REQUESTS` (Default: `200`): Max requests per window.
|
|
97
|
+
- `TOOL_TIMEOUT_MS` (Default: `60000` [1 min]): Tool execution timeout (ms).
|
|
98
|
+
|
|
99
|
+
## 🛠️ Tools
|
|
100
|
+
|
|
101
|
+
| Tool | Description | Parameters |
|
|
102
|
+
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
103
|
+
| **obsidian_list_files_in_vault** | Lists all files and directories within the root of your Obsidian vault. Returns a hierarchical structure detailing files, folders, and their types. | None |
|
|
104
|
+
| **obsidian_list_files_in_dir** | Lists files and directories within a specific folder in your Obsidian vault. Returns a hierarchical structure. Note: Empty directories may not be included in the results. Useful for exploring vault organization. | `dirpath*`: Path to list files from (relative to vault root). Note that empty directories will not be returned. |
|
|
105
|
+
| **obsidian_get_file_contents** | Retrieves the full content of a specified file within your Obsidian vault. Supports various readable file formats. | `filepath*`: Path to the relevant file (relative to your vault root). |
|
|
106
|
+
| **obsidian_append_content** | Appends the provided content to the end of a specified file in the vault. If the file does not exist, it will be created. | `filepath*`: Path to the file (relative to vault root)<br>`content*`: Content to append to the file |
|
|
107
|
+
| **obsidian_update_content** | Overwrites the entire content of a specified file in the vault with the provided content. If the file does not exist, it will be created. | `filepath*`: Path to the file (relative to vault root)<br>`content*`: The new, complete content for the file (overwrites existing content). |
|
|
108
|
+
| **obsidian_find_in_file** | Performs a full-text search across all files in your Obsidian vault. Returns matching files with context around each match. If more than 5 files match, only filenames and match counts are returned to avoid excessive output. Ideal for locating specific text, tags, or patterns. | `query*`: Text pattern to search for. Can include tags, keywords, or phrases.<br>`contextLength`: Number of characters surrounding each match to provide context (default: 10). |
|
|
109
|
+
| **obsidian_complex_search** | Finds files based on path patterns using JsonLogic queries. Primarily supports `glob` for pattern matching (e.g., '\*.md') and `var` for accessing the 'path' variable. Note: For content-based searches (full-text, tags within content, dates), use `obsidian_find_in_file`. | `query*`: A JsonLogic query object targeting file paths. Example: `{"glob": ["*.md", {"var": "path"}]}` matches all markdown files. |
|
|
110
|
+
| **obsidian_get_tags** | Retrieves all tags defined in the YAML frontmatter of markdown files within your Obsidian vault, along with their usage counts and associated file paths. Optionally, limit the search to a specific folder. | `path`: Optional folder path (relative to vault root) to restrict the tag search. |
|
|
111
|
+
| **obsidian_get_properties** | Retrieves properties (like title, tags, status) from the YAML frontmatter of a specified Obsidian note. Returns all defined properties, including any custom fields. | `filepath*`: Path to the note file (relative to vault root) |
|
|
112
|
+
| **obsidian_update_properties** | Updates properties within the YAML frontmatter of a specified Obsidian note. By default, array properties (like tags, type, status) are merged; use the 'replace' option to overwrite them instead. Handles custom fields and manages timestamps automatically. See schema for supported standard fields (title, author, tags, status, etc.). | `filepath*`: Path to the note file (relative to vault root)<br>`properties*`: Properties to update<br>`replace`: If true, array properties (like tags, status) will be completely replaced with the provided values instead of being merged with existing values. Defaults to false (merge). |
|
|
113
|
+
|
|
114
|
+
## 🔗 Resources
|
|
115
|
+
|
|
116
|
+
| Resource | Description | Returns |
|
|
117
|
+
| ------------------- | ----------------------------------------------------------------------- | ---------------- |
|
|
118
|
+
| **obsidian://tags** | List of all tags used across the Obsidian vault with their usage counts | application/json |
|
|
119
|
+
|
|
120
|
+
## 📁 Project Structure
|
|
118
121
|
|
|
119
122
|
The project follows a modular architecture with clear separation of concerns:
|
|
120
123
|
|
|
@@ -131,140 +134,7 @@ src/
|
|
|
131
134
|
└── utils/ # Shared utilities
|
|
132
135
|
```
|
|
133
136
|
|
|
134
|
-
##
|
|
135
|
-
|
|
136
|
-
### File Management
|
|
137
|
-
|
|
138
|
-
```typescript
|
|
139
|
-
// List vault contents
|
|
140
|
-
obsidian_list_files_in_vault: {
|
|
141
|
-
}
|
|
142
|
-
|
|
143
|
-
// List directory contents
|
|
144
|
-
obsidian_list_files_in_dir: {
|
|
145
|
-
dirpath: string; // Path relative to vault root
|
|
146
|
-
}
|
|
147
|
-
|
|
148
|
-
// Get file contents
|
|
149
|
-
obsidian_get_file_contents: {
|
|
150
|
-
filepath: string; // Path relative to vault root
|
|
151
|
-
}
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
### Search Operations
|
|
155
|
-
|
|
156
|
-
```typescript
|
|
157
|
-
// Text search with context
|
|
158
|
-
obsidian_find_in_file: {
|
|
159
|
-
query: string,
|
|
160
|
-
contextLength?: number // Default: 10
|
|
161
|
-
}
|
|
162
|
-
|
|
163
|
-
// Advanced search with JsonLogic
|
|
164
|
-
obsidian_complex_search: {
|
|
165
|
-
query: JsonLogicQuery
|
|
166
|
-
// Examples:
|
|
167
|
-
// Find by tag:
|
|
168
|
-
// {"in": ["#mytag", {"var": "frontmatter.tags"}]}
|
|
169
|
-
//
|
|
170
|
-
// Find markdown files in a directory:
|
|
171
|
-
// {"glob": ["docs/*.md", {"var": "path"}]}
|
|
172
|
-
//
|
|
173
|
-
// Combine conditions:
|
|
174
|
-
// {"and": [
|
|
175
|
-
// {"glob": ["*.md", {"var": "path"}]},
|
|
176
|
-
// {"in": ["#mytag", {"var": "frontmatter.tags"}]}
|
|
177
|
-
// ]}
|
|
178
|
-
}
|
|
179
|
-
|
|
180
|
-
// Get all tags in vault or directory
|
|
181
|
-
obsidian_get_tags: {
|
|
182
|
-
path?: string // Optional: limit to specific directory
|
|
183
|
-
}
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
### Content Modification
|
|
187
|
-
|
|
188
|
-
```typescript
|
|
189
|
-
// Append to file
|
|
190
|
-
obsidian_append_content: {
|
|
191
|
-
filepath: string, // Path relative to vault root
|
|
192
|
-
content: string // Content to append
|
|
193
|
-
}
|
|
194
|
-
|
|
195
|
-
// Update file content
|
|
196
|
-
obsidian_patch_content: {
|
|
197
|
-
filepath: string, // Path relative to vault root
|
|
198
|
-
content: string // New content (replaces existing)
|
|
199
|
-
}
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
### Property Management
|
|
203
|
-
|
|
204
|
-
```typescript
|
|
205
|
-
// Get note properties
|
|
206
|
-
obsidian_get_properties: {
|
|
207
|
-
filepath: string // Path relative to vault root
|
|
208
|
-
}
|
|
209
|
-
|
|
210
|
-
// Update note properties
|
|
211
|
-
obsidian_update_properties: {
|
|
212
|
-
filepath: string, // Path relative to vault root
|
|
213
|
-
properties: {
|
|
214
|
-
title?: string,
|
|
215
|
-
author?: string,
|
|
216
|
-
// Note: created/modified timestamps are managed automatically
|
|
217
|
-
type?: Array<"concept" | "architecture" | "specification" |
|
|
218
|
-
"protocol" | "api" | "research" | "implementation" |
|
|
219
|
-
"guide" | "reference">,
|
|
220
|
-
tags?: string[], // Must start with #
|
|
221
|
-
status?: Array<"draft" | "in-progress" | "review" | "complete">,
|
|
222
|
-
version?: string,
|
|
223
|
-
platform?: string,
|
|
224
|
-
repository?: string, // URL
|
|
225
|
-
dependencies?: string[],
|
|
226
|
-
sources?: string[],
|
|
227
|
-
urls?: string[], // URLs
|
|
228
|
-
papers?: string[],
|
|
229
|
-
custom?: Record<string, unknown>
|
|
230
|
-
}
|
|
231
|
-
}
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
## Best Practices
|
|
235
|
-
|
|
236
|
-
### File Operations
|
|
237
|
-
|
|
238
|
-
- Use atomic operations with validation
|
|
239
|
-
- Handle errors and monitor performance
|
|
240
|
-
|
|
241
|
-
### Search Implementation
|
|
242
|
-
|
|
243
|
-
- Use appropriate search tool for the task:
|
|
244
|
-
- obsidian_find_in_file for text search
|
|
245
|
-
- obsidian_complex_search for metadata/tag filtering
|
|
246
|
-
- Keep context size reasonable (default: 10 chars)
|
|
247
|
-
|
|
248
|
-
### Property Management
|
|
249
|
-
|
|
250
|
-
- Use appropriate types and validate updates
|
|
251
|
-
- Handle arrays and custom fields properly
|
|
252
|
-
- Never set timestamps (managed automatically)
|
|
253
|
-
|
|
254
|
-
### Error Prevention
|
|
255
|
-
|
|
256
|
-
- Validate inputs and handle errors gracefully
|
|
257
|
-
- Monitor patterns and respect rate limits
|
|
258
|
-
|
|
259
|
-
## Resources
|
|
260
|
-
|
|
261
|
-
The MCP server exposes the following resources:
|
|
262
|
-
|
|
263
|
-
```
|
|
264
|
-
obsidian://tags # List of all tags used across the vault
|
|
265
|
-
```
|
|
266
|
-
|
|
267
|
-
## Contributing
|
|
137
|
+
## 👥 Contributing
|
|
268
138
|
|
|
269
139
|
1. Fork the repository
|
|
270
140
|
2. Create a feature branch
|
|
@@ -272,19 +142,9 @@ obsidian://tags # List of all tags used across the vault
|
|
|
272
142
|
|
|
273
143
|
For bugs and features, create an issue at [https://github.com/cyanheads/obsidian-mcp-server/issues](https://github.com/cyanheads/obsidian-mcp-server/issues).
|
|
274
144
|
|
|
275
|
-
##
|
|
276
|
-
|
|
277
|
-
The package is automatically published to npm when version tags are pushed:
|
|
278
|
-
|
|
279
|
-
```bash
|
|
280
|
-
# Update version in package.json
|
|
281
|
-
npm version patch # or minor, or major
|
|
282
|
-
git push --follow-tags
|
|
283
|
-
```
|
|
284
|
-
|
|
285
|
-
This will trigger the GitHub Action to build and publish the package.
|
|
145
|
+
## 📄 License
|
|
286
146
|
|
|
287
|
-
|
|
147
|
+
[](https://opensource.org/licenses/Apache-2.0)
|
|
288
148
|
|
|
289
149
|
Apache License 2.0
|
|
290
150
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "obsidian-mcp-server",
|
|
3
|
-
"version": "1.5.
|
|
3
|
+
"version": "1.5.7",
|
|
4
4
|
"description": "Model Context Protocol (MCP) server designed for LLMs to interact with Obsidian vaults. Provides secure, token-aware tools for seamless knowledge base management through a standardized interface.",
|
|
5
5
|
"main": "build/index.js",
|
|
6
6
|
"type": "module",
|
|
@@ -16,12 +16,15 @@
|
|
|
16
16
|
"rebuild": "npm run clean && npm run build",
|
|
17
17
|
"tree": "npx ts-node --esm scripts/tree.ts"
|
|
18
18
|
},
|
|
19
|
+
"bin": {
|
|
20
|
+
"obsidian-mcp-server": "build/index.js"
|
|
21
|
+
},
|
|
19
22
|
"dependencies": {
|
|
20
23
|
"@modelcontextprotocol/sdk": "^1.10.2",
|
|
21
|
-
"@types/node": "^22.
|
|
22
|
-
"@typescript-eslint/eslint-plugin": "^8.31.
|
|
23
|
-
"@typescript-eslint/parser": "^8.31.
|
|
24
|
-
"axios": "^1.
|
|
24
|
+
"@types/node": "^22.15.3",
|
|
25
|
+
"@typescript-eslint/eslint-plugin": "^8.31.1",
|
|
26
|
+
"@typescript-eslint/parser": "^8.31.1",
|
|
27
|
+
"axios": "^1.9.0",
|
|
25
28
|
"dotenv": "^16.5.0",
|
|
26
29
|
"eslint": "^9.25.1",
|
|
27
30
|
"eslint-config-prettier": "^10.1.2",
|