@fazer-ai/mcp-obsidian 1.0.15 → 1.1.0
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/LICENSE +21 -0
- package/README.md +89 -109
- package/dist/index.js +1 -1
- package/package.json +1 -1
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2024 Markus Pfundstein
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -12,166 +12,146 @@
|
|
|
12
12
|
|
|
13
13
|
| Tool name | Description |
|
|
14
14
|
|-----------|-------------|
|
|
15
|
-
| **
|
|
16
|
-
| **
|
|
17
|
-
| **
|
|
18
|
-
| **
|
|
19
|
-
| **
|
|
20
|
-
| **
|
|
21
|
-
| **
|
|
22
|
-
| **
|
|
23
|
-
| **
|
|
24
|
-
| **
|
|
25
|
-
| **
|
|
26
|
-
| **
|
|
27
|
-
| **
|
|
28
|
-
| **
|
|
29
|
-
| **
|
|
30
|
-
| **
|
|
31
|
-
| **
|
|
32
|
-
| **
|
|
33
|
-
| **
|
|
34
|
-
| **
|
|
35
|
-
| **
|
|
36
|
-
| **
|
|
37
|
-
| **
|
|
38
|
-
| **
|
|
39
|
-
|
|
40
|
-
*See [Local REST API specifications](https://coddingtonbear.github.io/obsidian-local-rest-api) for more details.*
|
|
15
|
+
| **obsidian_status** | Returns basic details about the Obsidian Local REST API server and your authentication status |
|
|
16
|
+
| **obsidian_delete_active** | Deletes the note that is currently active in the Obsidian UI |
|
|
17
|
+
| **obsidian_get_active** | Retrieves the full content of the active note (Markdown or JSON view) |
|
|
18
|
+
| **obsidian_patch_active** | Inserts, replaces or prepends content in the active note relative to a heading, block reference, or front-matter field |
|
|
19
|
+
| **obsidian_post_active** | Appends Markdown to the end of the active note |
|
|
20
|
+
| **obsidian_put_active** | Replaces the entire body of the active note |
|
|
21
|
+
| **obsidian_get_commands** | Lists every command available in Obsidian’s command palette |
|
|
22
|
+
| **obsidian_execute_command** | Executes a specific Obsidian command by its ID |
|
|
23
|
+
| **obsidian_open_file** | Opens the given file inside Obsidian (creates it if missing); optional flag to open in a new leaf |
|
|
24
|
+
| **obsidian_delete_periodic** | Deletes the current daily / weekly / monthly / quarterly / yearly note for the requested period |
|
|
25
|
+
| **obsidian_get_periodic** | Returns the content of the current periodic note for the requested period |
|
|
26
|
+
| **obsidian_patch_periodic** | Inserts / replaces content in a periodic note relative to a heading, block reference, or front-matter field |
|
|
27
|
+
| **obsidian_post_periodic** | Appends Markdown to the periodic note (creates it if it doesn’t exist) |
|
|
28
|
+
| **obsidian_put_periodic** | Replaces the entire body of a periodic note |
|
|
29
|
+
| **obsidian_search_dataview** | Runs a Dataview-DQL query across the vault and returns matching rows |
|
|
30
|
+
| **obsidian_search_json_logic** | Runs a JsonLogic query against structured note metadata |
|
|
31
|
+
| **obsidian_simple_search** | Performs a plain-text fuzzy search with optional surrounding context |
|
|
32
|
+
| **obsidian_list_vault_root** | Lists all files and directories at the **root** of your vault |
|
|
33
|
+
| **obsidian_list_vault_directory** | Lists files and directories inside a **specific folder** of the vault |
|
|
34
|
+
| **obsidian_delete_file** | Deletes a specific file (or directory) in the vault |
|
|
35
|
+
| **obsidian_get_file** | Retrieves the content of a file in the vault (Markdown or JSON view) |
|
|
36
|
+
| **obsidian_patch_file** | Inserts / replaces content in an arbitrary file relative to a heading, block reference, or front-matter field |
|
|
37
|
+
| **obsidian_post_file** | Appends Markdown to a file (creates it if it doesn’t exist) |
|
|
38
|
+
| **obsidian_put_file** | Creates a new file or replaces the entire body of an existing file |
|
|
39
|
+
|
|
40
|
+
*See Obsidian's [Local REST API specifications](https://coddingtonbear.github.io/obsidian-local-rest-api) for more details.*
|
|
41
41
|
|
|
42
42
|
---
|
|
43
43
|
|
|
44
44
|
### Example prompts
|
|
45
45
|
|
|
46
46
|
```text
|
|
47
|
-
#
|
|
47
|
+
# Summarize the latest “architecture call” note
|
|
48
48
|
# (Claude will transparently call list_files_in_vault → get_file_contents)
|
|
49
|
-
Get the contents of the last “architecture call” note and
|
|
49
|
+
Get the contents of the last “architecture call” note and summarize them.
|
|
50
50
|
|
|
51
51
|
# Find all mentions of Cosmos DB
|
|
52
52
|
Search for all files where “Azure CosmosDb” is mentioned and explain the context briefly.
|
|
53
53
|
|
|
54
54
|
# Create a summary note
|
|
55
|
-
|
|
56
|
-
“summaries/2025-04-24-meeting.md”. Add a short intro suitable for e-mail.
|
|
55
|
+
Summarize yesterday’s meeting and save it as “summaries/2025-04-24-meeting.md”. Add a short intro suitable for e-mail.
|
|
57
56
|
```
|
|
58
57
|
|
|
59
58
|
---
|
|
60
59
|
|
|
61
60
|
## ⚙️ Configuration
|
|
62
61
|
|
|
63
|
-
### Environment variables
|
|
64
|
-
|
|
65
|
-
Copy `.env.example` to `.env` and fill in your values:
|
|
66
|
-
|
|
67
|
-
```bash
|
|
68
|
-
PORT=3045 # TCP port the MCP server will listen on
|
|
69
|
-
OBSIDIAN_API_KEY= # Obtain this from the plugin settings in Obsidian
|
|
70
|
-
OBSIDIAN_PROTOCOL=http
|
|
71
|
-
OBSIDIAN_HOST=localhost
|
|
72
|
-
OBSIDIAN_PORT=27123 # Port the Local REST API plugin is bound to
|
|
73
|
-
```
|
|
74
|
-
|
|
75
62
|
### Obsidian REST API key
|
|
76
63
|
|
|
77
|
-
|
|
64
|
+
There are two ways to pass the Obsidian API key to the server:
|
|
78
65
|
|
|
79
66
|
1. **Server config (recommended)** – pass it via the `env` field in your Claude (or other client) MCP-server declaration:
|
|
80
67
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
2. **`.env` file** – place the key in the `.env` you created above.
|
|
68
|
+
```jsonc
|
|
69
|
+
// claude_desktop_config.json
|
|
70
|
+
{
|
|
71
|
+
"mcpServers": {
|
|
72
|
+
"@fazer-ai/mcp-obsidian": {
|
|
73
|
+
"command": "bunx",
|
|
74
|
+
"args": ["@fazer-ai/mcp-obsidian@latest"],
|
|
75
|
+
"env": {
|
|
76
|
+
"OBSIDIAN_API_KEY": "your-obsidian-api-key"
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
```
|
|
97
82
|
|
|
98
|
-
|
|
83
|
+
>[!NOTE]
|
|
84
|
+
> Use `@fazer-ai/mcp-obsidian@latest` to ensure you always run the most up to date version of the server.
|
|
99
85
|
|
|
100
|
-
|
|
86
|
+
2. Alternatively, you can use an **`.env` file**. Place the key in the `.env` you created above. Note it must be placed in the working directory where the MCP server is running.
|
|
101
87
|
|
|
102
|
-
### Prerequisites
|
|
103
88
|
|
|
104
|
-
|
|
105
|
-
* Obsidian with the **Local REST API** plugin enabled.
|
|
89
|
+
### Environment variables
|
|
106
90
|
|
|
107
|
-
|
|
91
|
+
You can use the `.env.example` file as reference to create your own `.env` file.
|
|
108
92
|
|
|
109
93
|
```bash
|
|
110
|
-
#
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
# 2. Configure env vars
|
|
116
|
-
cp .env.example .env # then edit as needed
|
|
117
|
-
|
|
118
|
-
# 3. Launch the server
|
|
119
|
-
bunx mcp-obsidian-ts # starts on $PORT (default 3045)
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
When the server starts you should see:
|
|
123
|
-
|
|
124
|
-
```
|
|
125
|
-
▶ MCP server (obsidian) listening on http://localhost:3045
|
|
94
|
+
PORT=3045 # TCP port the MCP server will listen on
|
|
95
|
+
OBSIDIAN_API_KEY= # Obtain this from the plugin settings in Obsidian
|
|
96
|
+
OBSIDIAN_PROTOCOL=http
|
|
97
|
+
OBSIDIAN_HOST=localhost
|
|
98
|
+
OBSIDIAN_PORT=27123 # Port the Local REST API plugin is bound to
|
|
126
99
|
```
|
|
127
100
|
|
|
128
|
-
Add / update the entry in your Claude Desktop or MCP-compatible client and you’re ready to chat with your vault.
|
|
129
|
-
|
|
130
101
|
---
|
|
131
102
|
|
|
132
103
|
## 🛠 Development
|
|
133
104
|
|
|
134
|
-
###
|
|
105
|
+
### Running local version on Claude Desktop
|
|
106
|
+
|
|
107
|
+
After cloning this repo, you can update Claude's config to run your local version of the server instead of pulling from npm.
|
|
108
|
+
This is useful for quickly testing changes before publishing.
|
|
109
|
+
|
|
110
|
+
>[!NOTE]
|
|
111
|
+
>Keep in mind any changes you make on the code will only take effect after restarting the Claude Desktop app.
|
|
112
|
+
|
|
113
|
+
1. Clone this repo and run `bun install` to install dependencies.
|
|
114
|
+
1. Update your `claude_desktop_config.json` to point to your local version of the server:
|
|
115
|
+
|
|
116
|
+
```jsonc
|
|
117
|
+
// claude_desktop_config.json
|
|
118
|
+
{
|
|
119
|
+
"mcpServers": {
|
|
120
|
+
"@fazer-ai/mcp-obsidian": {
|
|
121
|
+
"command": "bun",
|
|
122
|
+
"args": ["/path/to/repo/src/index.ts"],
|
|
123
|
+
"env": {
|
|
124
|
+
"OBSIDIAN_API_KEY": "your-obsidian-api-key"
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
```
|
|
135
130
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
| `bun run dev` | Starts the server with live-reload (tsx) |
|
|
139
|
-
| `bun run build` | Bundles to `dist/` (ESM) |
|
|
140
|
-
| `bun test` | Runs unit tests (vitest) |
|
|
131
|
+
>[!IMPORTANT]
|
|
132
|
+
>Note we use `bun` instead of `bunx` here.
|
|
141
133
|
|
|
142
134
|
### Debugging
|
|
143
135
|
|
|
144
136
|
MCP servers talk over **stdio**, so normal debuggers aren’t helpful.
|
|
145
|
-
Use the
|
|
137
|
+
Use the **[MCP Inspector](https://github.com/modelcontextprotocol/inspector)**:
|
|
146
138
|
|
|
147
139
|
```bash
|
|
148
|
-
npx @modelcontextprotocol/inspector
|
|
140
|
+
npx @modelcontextprotocol/inspector bun /path/to/repo/src/index.ts
|
|
149
141
|
```
|
|
150
142
|
|
|
151
|
-
Open the URL it prints to step through requests, inspect tool calls, and watch logs in real time.
|
|
152
|
-
Alternatively, tail the log file written by Claude Desktop:
|
|
153
|
-
|
|
154
|
-
```bash
|
|
155
|
-
tail -f ~/Library/Logs/Claude/mcp-server-mcp-obsidian-ts.log
|
|
156
|
-
```
|
|
143
|
+
Open the URL it prints to step through requests (usually http://localhost:6274), inspect tool calls, and watch logs in real time.
|
|
157
144
|
|
|
158
145
|
---
|
|
159
146
|
|
|
160
147
|
## 📦 Publishing
|
|
161
148
|
|
|
162
|
-
1.
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
---
|
|
167
|
-
|
|
168
|
-
### Licence
|
|
169
|
-
|
|
170
|
-
MIT – see [LICENCE](LICENCE).
|
|
149
|
+
1. Update the version in `package.json`.
|
|
150
|
+
1. Create GitHub release.
|
|
151
|
+
1. Run `bun publish`.
|
|
171
152
|
|
|
172
153
|
---
|
|
173
154
|
|
|
174
|
-
|
|
175
|
-
```
|
|
155
|
+
## License
|
|
176
156
|
|
|
177
|
-
|
|
157
|
+
MIT – see [LICENSE](LICENSE).
|
package/dist/index.js
CHANGED