Release v1.0.0 - Initial Release
🎉 Initial release of Obsidian MCP Server plugin
Core Features:
- MCP server implementation with HTTP transport
- JSON-RPC 2.0 message handling
- Protocol version 2024-11-05 support
MCP Tools:
- read_note, create_note, update_note, delete_note
- search_notes, list_notes, get_vault_info
Server Features:
- Configurable HTTP server (default port: 3000)
- Health check and MCP endpoints
- Auto-start option
Security:
- Origin header validation (DNS rebinding protection)
- Optional Bearer token authentication
- CORS configuration
UI:
- Settings panel with full configuration
- Status bar indicator and ribbon icon
- Start/Stop/Restart commands
Documentation:
- Comprehensive README with examples
- Quick Start Guide and Implementation Summary
- Test client script
This commit is contained in:
255
README.md
Normal file
255
README.md
Normal file
@@ -0,0 +1,255 @@
|
||||
# Obsidian MCP Server Plugin
|
||||
|
||||
An Obsidian plugin that exposes your vault operations via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) over HTTP. This allows AI assistants and other MCP clients to interact with your Obsidian vault programmatically.
|
||||
|
||||
## Features
|
||||
|
||||
- **HTTP MCP Server**: Runs an HTTP server implementing the MCP protocol
|
||||
- **Vault Operations**: Exposes tools for reading, creating, updating, and deleting notes
|
||||
- **Search Functionality**: Search notes by content or filename
|
||||
- **Security**: Localhost-only binding, optional authentication, CORS configuration
|
||||
- **Easy Configuration**: Simple settings UI with server status and controls
|
||||
|
||||
## Available MCP Tools
|
||||
|
||||
- `read_note` - Read the content of a note
|
||||
- `create_note` - Create a new note
|
||||
- `update_note` - Update an existing note
|
||||
- `delete_note` - Delete a note
|
||||
- `search_notes` - Search for notes by query
|
||||
- `list_notes` - List all notes or notes in a folder
|
||||
- `get_vault_info` - Get vault metadata
|
||||
|
||||
## Installation
|
||||
|
||||
### From Source
|
||||
|
||||
1. Clone this repository into your vault's plugins folder:
|
||||
```bash
|
||||
cd /path/to/vault/.obsidian/plugins
|
||||
git clone <repository-url> obsidian-mcp-server
|
||||
cd obsidian-mcp-server
|
||||
```
|
||||
|
||||
2. Install dependencies:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. Build the plugin:
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
4. Enable the plugin in Obsidian Settings → Community Plugins
|
||||
|
||||
## Configuration
|
||||
|
||||
1. Open Obsidian Settings → MCP Server
|
||||
2. Configure the following options:
|
||||
- **Port**: HTTP server port (default: 3000)
|
||||
- **Auto-start**: Automatically start server on Obsidian launch
|
||||
- **Enable CORS**: Allow cross-origin requests
|
||||
- **Allowed Origins**: Comma-separated list of allowed origins
|
||||
- **Enable Authentication**: Require API key for requests
|
||||
- **API Key**: Bearer token for authentication
|
||||
|
||||
3. Click "Start Server" or use the ribbon icon to toggle the server
|
||||
|
||||
## Usage
|
||||
|
||||
### Starting the Server
|
||||
|
||||
- **Via Ribbon Icon**: Click the server icon in the left sidebar
|
||||
- **Via Command Palette**: Run "Start MCP Server"
|
||||
- **Auto-start**: Enable in settings to start automatically
|
||||
|
||||
### Connecting an MCP Client
|
||||
|
||||
The server exposes an MCP endpoint at:
|
||||
```
|
||||
http://127.0.0.1:3000/mcp
|
||||
```
|
||||
|
||||
Example client configuration (e.g., for Claude Desktop):
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"obsidian": {
|
||||
"url": "http://127.0.0.1:3000/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Using with Authentication
|
||||
|
||||
If authentication is enabled, include the API key in requests:
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:3000/mcp \
|
||||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
|
||||
```
|
||||
|
||||
## Example MCP Requests
|
||||
|
||||
### Initialize Connection
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "initialize",
|
||||
"params": {
|
||||
"protocolVersion": "2024-11-05",
|
||||
"capabilities": {},
|
||||
"clientInfo": {
|
||||
"name": "example-client",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### List Available Tools
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 2,
|
||||
"method": "tools/list"
|
||||
}
|
||||
```
|
||||
|
||||
### Read a Note
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 3,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "read_note",
|
||||
"arguments": {
|
||||
"path": "folder/note.md"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Create a Note
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 4,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "create_note",
|
||||
"arguments": {
|
||||
"path": "new-note.md",
|
||||
"content": "# New Note\n\nThis is the content."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Search Notes
|
||||
```json
|
||||
{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 5,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "search_notes",
|
||||
"arguments": {
|
||||
"query": "search term"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- **Localhost Only**: The server binds to `127.0.0.1` to prevent external access
|
||||
- **Origin Validation**: Validates request origins to prevent DNS rebinding attacks
|
||||
- **Optional Authentication**: Use API keys to restrict access
|
||||
- **Desktop Only**: This plugin only works on desktop (not mobile) due to HTTP server requirements
|
||||
|
||||
## Development
|
||||
|
||||
### Building from Source
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev # Watch mode for development
|
||||
npm run build # Production build
|
||||
```
|
||||
- Make changes to `main.ts` (or create new `.ts` files). Those changes should be automatically compiled into `main.js`.
|
||||
- Reload Obsidian to load the new version of your plugin.
|
||||
- Enable plugin in settings window.
|
||||
- For updates to the Obsidian API run `npm update` in the command line under your repo folder.
|
||||
|
||||
## Releasing new releases
|
||||
|
||||
- Update your `manifest.json` with your new version number, such as `1.0.1`, and the minimum Obsidian version required for your latest release.
|
||||
- Update your `versions.json` file with `"new-plugin-version": "minimum-obsidian-version"` so older versions of Obsidian can download an older version of your plugin that's compatible.
|
||||
- Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix `v`. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases
|
||||
- Upload the files `manifest.json`, `main.js`, `styles.css` as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release.
|
||||
- Publish the release.
|
||||
|
||||
> You can simplify the version bump process by running `npm version patch`, `npm version minor` or `npm version major` after updating `minAppVersion` manually in `manifest.json`.
|
||||
> The command will bump version in `manifest.json` and `package.json`, and add the entry for the new version to `versions.json`
|
||||
|
||||
## Adding your plugin to the community plugin list
|
||||
|
||||
- Check the [plugin guidelines](https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines).
|
||||
- Publish an initial version.
|
||||
- Make sure you have a `README.md` file in the root of your repo.
|
||||
- Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin.
|
||||
|
||||
## How to use
|
||||
|
||||
- Clone this repo.
|
||||
- Make sure your NodeJS is at least v16 (`node --version`).
|
||||
- `npm i` or `yarn` to install dependencies.
|
||||
- `npm run dev` to start compilation in watch mode.
|
||||
|
||||
## Manually installing the plugin
|
||||
|
||||
- Copy over `main.js`, `styles.css`, `manifest.json` to your vault `VaultFolder/.obsidian/plugins/your-plugin-id/`.
|
||||
|
||||
## Improve code quality with eslint (optional)
|
||||
- [ESLint](https://eslint.org/) is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code.
|
||||
- To use eslint with this project, make sure to install eslint from terminal:
|
||||
- `npm install -g eslint`
|
||||
- To use eslint to analyze this project use this command:
|
||||
- `eslint main.ts`
|
||||
- eslint will then create a report with suggestions for code improvement by file and line number.
|
||||
- If your source code is in a folder, such as `src`, you can use eslint with this command to analyze all files in that folder:
|
||||
- `eslint ./src/`
|
||||
|
||||
## Funding URL
|
||||
|
||||
You can include funding URLs where people who use your plugin can financially support it.
|
||||
|
||||
The simple way is to set the `fundingUrl` field to your link in your `manifest.json` file:
|
||||
|
||||
```json
|
||||
{
|
||||
"fundingUrl": "https://buymeacoffee.com"
|
||||
}
|
||||
```
|
||||
|
||||
If you have multiple URLs, you can also do:
|
||||
|
||||
```json
|
||||
{
|
||||
"fundingUrl": {
|
||||
"Buy Me a Coffee": "https://buymeacoffee.com",
|
||||
"GitHub Sponsor": "https://github.com/sponsors",
|
||||
"Patreon": "https://www.patreon.com/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## API Documentation
|
||||
|
||||
See https://github.com/obsidianmd/obsidian-api
|
||||
Reference in New Issue
Block a user