@fazer-ai/mcp-obsidian 1.0.15 → 1.1.1

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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +89 -110
  3. package/dist/index.js +2 -9
  4. package/package.json +10 -3
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
@@ -1,6 +1,6 @@
1
1
  # MCP server for Obsidian (TypeScript + Bun)
2
2
 
3
- ![NPM Version](https://img.shields.io/npm/v/%40fazer-ai%2Fmcp-obsidian)
3
+ [![NPM Version](https://img.shields.io/npm/v/%40fazer-ai%2Fmcp-obsidian)](https://www.npmjs.com/package/@fazer-ai/mcp-obsidian)
4
4
 
5
5
  > A Model-Context-Protocol (MCP) server that lets Claude (or any MCP-compatible LLM) interact with your Obsidian vault through the [**Local REST API**](https://github.com/coddingtonbear/obsidian-local-rest-api) community plugin – written in **TypeScript** and runnable with **bunx**.
6
6
 
@@ -12,166 +12,145 @@
12
12
 
13
13
  | Tool name | Description |
14
14
  |-----------|-------------|
15
- | **status** | Returns basic details about the Obsidian Local REST API server and your authentication status |
16
- | **delete_active** | Deletes the note that is currently active in the Obsidian UI |
17
- | **get_active** | Retrieves the full content of the active note (Markdown or JSON view) |
18
- | **patch_active** | Inserts, replaces or prepends content in the active note relative to a heading, block reference, or front-matter field |
19
- | **post_active** | Appends Markdown to the end of the active note |
20
- | **put_active** | Replaces the entire body of the active note |
21
- | **get_commands** | Lists every command available in Obsidian’s command palette |
22
- | **execute_command** | Executes a specific Obsidian command by its ID |
23
- | **open_file** | Opens the given file inside Obsidian (creates it if missing); optional flag to open in a new leaf |
24
- | **delete_periodic** | Deletes the current daily / weekly / monthly / quarterly / yearly note for the requested period |
25
- | **get_periodic** | Returns the content of the current periodic note for the requested period |
26
- | **patch_periodic** | Inserts / replaces content in a periodic note relative to a heading, block reference, or front-matter field |
27
- | **post_periodic** | Appends Markdown to the periodic note (creates it if it doesn’t exist) |
28
- | **put_periodic** | Replaces the entire body of a periodic note |
29
- | **search_dataview** | Runs a Dataview-DQL query across the vault and returns matching rows |
30
- | **search_json_logic** | Runs a JsonLogic query against structured note metadata |
31
- | **simple_search** | Performs a plain-text fuzzy search with optional surrounding context |
32
- | **list_vault_root** | Lists all files and directories at the **root** of your vault |
33
- | **list_vault_directory** | Lists files and directories inside a **specific folder** of the vault |
34
- | **delete_file** | Deletes a specific file (or directory) in the vault |
35
- | **get_file** | Retrieves the content of a file in the vault (Markdown or JSON view) |
36
- | **patch_file** | Inserts / replaces content in an arbitrary file relative to a heading, block reference, or front-matter field |
37
- | **post_file** | Appends Markdown to a file (creates it if it doesn’t exist) |
38
- | **put_file** | Creates a new file or replaces the entire body of an existing file |
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
- # Summarise the latest “architecture call” note
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 summarise them.
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
- Summarise yesterday’s meeting and save it as
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
- You can supply the key either by:
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
- ```jsonc
82
- {
83
- "mcpServers": {
84
- "mcp-obsidian-ts": {
85
- "command": "bunx",
86
- "args": ["mcp-obsidian-ts"], // or the binary of your package
87
- "env": {
88
- "OBSIDIAN_API_KEY": "paste_key_here",
89
- "OBSIDIAN_HOST": "localhost"
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
- ## 🚀 Quickstart
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
- * **Bun** ≥ 1.1 → <https://bun.sh/docs/installation>
105
- * Obsidian with the **Local REST API** plugin enabled.
89
+ ### Environment variables
106
90
 
107
- ### Install & run
91
+ You can use the `.env.example` file as reference to create your own `.env` file.
108
92
 
109
93
  ```bash
110
- # 1. Grab the package
111
- git clone https://github.com/your-org/mcp-obsidian-ts.git
112
- cd mcp-obsidian-ts
113
- bun install
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
+ OBSIDIAN_API_KEY= # Obtain this from the plugin settings in Obsidian
95
+ OBSIDIAN_PROTOCOL=http
96
+ OBSIDIAN_HOST=localhost
97
+ OBSIDIAN_PORT=27123 # Port the Local REST API plugin is bound to
126
98
  ```
127
99
 
128
- Add / update the entry in your Claude Desktop or MCP-compatible client and you’re ready to chat with your vault.
129
-
130
100
  ---
131
101
 
132
102
  ## 🛠 Development
133
103
 
134
- ### Scripts
104
+ ### Running local version on Claude Desktop
105
+
106
+ After cloning this repo, you can update Claude's config to run your local version of the server instead of pulling from npm.
107
+ This is useful for quickly testing changes before publishing.
108
+
109
+ >[!NOTE]
110
+ >Keep in mind any changes you make on the code will only take effect after restarting the Claude Desktop app.
111
+
112
+ 1. Clone this repo and run `bun install` to install dependencies.
113
+ 1. Update your `claude_desktop_config.json` to point to your local version of the server:
114
+
115
+ ```jsonc
116
+ // claude_desktop_config.json
117
+ {
118
+ "mcpServers": {
119
+ "@fazer-ai/mcp-obsidian": {
120
+ "command": "bun",
121
+ "args": ["/path/to/repo/src/index.ts"],
122
+ "env": {
123
+ "OBSIDIAN_API_KEY": "your-obsidian-api-key"
124
+ }
125
+ }
126
+ }
127
+ }
128
+ ```
135
129
 
136
- | Script | What it does |
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) |
130
+ >[!IMPORTANT]
131
+ >Note we use `bun` instead of `bunx` here.
141
132
 
142
133
  ### Debugging
143
134
 
144
135
  MCP servers talk over **stdio**, so normal debuggers aren’t helpful.
145
- Use the excellent **[MCP Inspector]**:
136
+ Use the **[MCP Inspector](https://github.com/modelcontextprotocol/inspector)**:
146
137
 
147
138
  ```bash
148
- npx @modelcontextprotocol/inspector bunx --directory /path/to/mcp-obsidian-ts run dev
139
+ npx @modelcontextprotocol/inspector bun /path/to/repo/src/index.ts
149
140
  ```
150
141
 
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
- ```
142
+ Open the URL it prints to step through requests (usually http://localhost:6274), inspect tool calls, and watch logs in real time.
157
143
 
158
144
  ---
159
145
 
160
146
  ## 📦 Publishing
161
147
 
162
- 1. Run `bun run build`.
163
- 2. `npm publish --access public` (or `np`, `release-it`, etc.).
164
- 3. Update the badge URL at the top of this file with the server ID from <https://glama.ai/mcp>.
165
-
166
- ---
167
-
168
- ### Licence
169
-
170
- MIT – see [LICENCE](LICENCE).
148
+ 1. Update the version in `package.json`.
149
+ 1. Create GitHub release.
150
+ 1. Run `bun publish`.
171
151
 
172
152
  ---
173
153
 
174
- **Happy note-wrangling!** 🗒️✨
175
- ```
154
+ ## License
176
155
 
177
- *Tip:* If your project has its own name (e.g. **`mcp-obsidian-ts`**) just swap it in wherever you see a placeholder.
156
+ MIT – see [LICENSE](LICENSE).
package/dist/index.js CHANGED
@@ -1,13 +1,6 @@
1
1
  // src/config.ts
2
- var {
3
- PORT,
4
- OBSIDIAN_API_KEY,
5
- OBSIDIAN_PROTOCOL,
6
- OBSIDIAN_HOST,
7
- OBSIDIAN_PORT
8
- } = process.env;
2
+ var { OBSIDIAN_API_KEY, OBSIDIAN_PROTOCOL, OBSIDIAN_HOST, OBSIDIAN_PORT } = process.env;
9
3
  var config = {
10
- port: PORT ? Number(PORT) : 3045,
11
4
  obsidian: {
12
5
  apiKey: OBSIDIAN_API_KEY || "",
13
6
  protocol: OBSIDIAN_PROTOCOL || "http",
@@ -7172,7 +7165,7 @@ class StdioServerTransport {
7172
7165
 
7173
7166
  // package.json
7174
7167
  var name = "@fazer-ai/mcp-obsidian";
7175
- var version = "1.0.15";
7168
+ var version = "1.1.1";
7176
7169
 
7177
7170
  // src/index.ts
7178
7171
  var server = new McpServer({ name, version }, {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fazer-ai/mcp-obsidian",
3
- "version": "1.0.15",
3
+ "version": "1.1.1",
4
4
  "module": "src/index.ts",
5
5
  "main": "dist/index.js",
6
6
  "bin": "dist/index.js",
@@ -16,6 +16,14 @@
16
16
  "publishConfig": {
17
17
  "access": "public"
18
18
  },
19
+ "keywords": [
20
+ "mcp",
21
+ "mcp-obsidian",
22
+ "modelcontextprotocol",
23
+ "claude",
24
+ "obsidian",
25
+ "fazer-ai"
26
+ ],
19
27
  "scripts": {
20
28
  "dev": "bun run --watch src/index.ts",
21
29
  "build": "bun build src/index.ts --target node --outdir=dist",
@@ -25,8 +33,7 @@
25
33
  },
26
34
  "devDependencies": {
27
35
  "@biomejs/biome": "1.9.4",
28
- "@types/bun": "latest",
29
- "@types/express": "^5.0.1"
36
+ "@types/bun": "latest"
30
37
  },
31
38
  "peerDependencies": {
32
39
  "typescript": "^5"