Potencia tu agente
Instalación del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
Aún no hay una versión empaquetada en el registro. Sigue el README del repositorio.
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirA Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with your Obsidian vault. Access your notes, create content, manage tags, and search your knowledge base through natural conversation.
DATABASE_URL is setHow clients connect: the server speaks MCP over HTTP + SSE only (there is no stdio mode). You start it (npx, Docker or from source), then point a client at http://HOST:PORT/sse. Clients that only support stdio servers connect through mcp-remote, as shown below. It listens on all network interfaces on PORT, so set an API_KEY (see Authentication) or keep it on loopback (for example -p 127.0.0.1:3001:3000 in Docker) unless you want the whole network to have read/write access to your vault.
Requires Node.js 20.19 or newer. This starts the server in the foreground (default port 3000):
VAULT_PATH=/path/to/your/vault npx @smith-and-web/obsidian-mcp-server
With options:
VAULT_PATH=/path/to/vault PORT=3001 COMPACT_RESPONSES=true npx @smith-and-web/obsidian-mcp-server
Using the pre-built image from GitHub Container Registry:
docker run -d \
--name obsidian-mcp \
-v /path/to/your/vault:/vault:rw \
-p 127.0.0.1:3001:3000 \
-e VAULT_PATH=/vault \
ghcr.io/smith-and-web/obsidian-mcp-server:latest
latest follows the newest release; pin a version tag (for example :1.6.0) for production. Drop 127.0.0.1: only if you set API_KEY and want other machines to connect.
Or with Docker Compose:
Create a docker-compose.yml:
services:
obsidian-mcp:
image: ghcr.io/smith-and-web/obsidian-mcp-server:latest
container_name: obsidian-mcp
restart: unless-stopped
volumes:
- /path/to/your/vault:/vault:rw
ports:
- "127.0.0.1:3001:3000"
environment:
- VAULT_PATH=/vault
Start the server
docker compose up -d
Verify it's running
curl http://localhost:3001/health
Install dependencies
npm install
Set environment variables
export VAULT_PATH=/path/to/your/vault
export PORT=3000
Start the server
npm start
# Or with auto-reload:
npm run dev
Add to your Claude Desktop config file:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonOption 1: Local server (via mcp-remote)
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3001/sse"]
}
}
}
Option 2: Remote server with HTTPS
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://your-domain.com/sse"]
}
}
}
The server must already be running (see Quick Start). Claude Desktop launches mcp-remote, which bridges its stdio to the server's SSE endpoint; Claude Desktop cannot launch this server directly, because the server does not speak stdio.
Add to your Cursor MCP settings (Settings → MCP):
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3001/sse"]
}
}
}
Claude Code supports SSE servers directly:
claude mcp add --transport sse obsidian http://localhost:3001/sse
# with an API key:
claude mcp add --transport sse obsidian https://your-host/sse --header "Authorization: Bearer your-secret-key"
Any other MCP-compatible client can connect using mcp-remote:
npx mcp-remote http://localhost:3001/sse
Or connect directly to the SSE endpoint at http://localhost:3001/sse if the client supports SSE servers natively.
DATABASE_URL is set)See Semantic search for setup.
┌─────────────────┐ HTTPS/SSE ┌──────────────────┐
│ Claude Desktop │ ◄────────────────► │ MCP Server │
└─────────────────┘ │ (Express.js) │
└────────┬─────────┘
│
┌────────▼─────────┐
│ VaultManager │
│ (File System) │
└────────┬─────────┘
│
┌────────▼─────────┐
│ Obsidian Vault │
│ (Markdown) │
└──────────────────┘
obsidian-mcp-server/
├── src/
│ ├── index.ts # Express server entry point
│ ├── vault/
│ │ ├── VaultManager.ts # Core vault operations
│ │ └── frontmatter.ts # YAML parsing utilities
│ ├── tools/
│ │ ├── definitions.ts # MCP tool schemas
│ │ ├── handlers.ts # Tool execution logic
│ │ └── index.ts # Tool exports
│ ├── server/
│ │ ├── mcp.ts # MCP protocol handlers
│ │ └── middleware.ts # Express middleware
│ ├── index/ # Optional semantic search
│ │ ├── config.ts # DATABASE_URL / OLLAMA_URL / EMBED_MODEL
│ │ ├── exclusions.ts # What the indexer never reads
│ │ ├── chunker.ts # Heading-aware chunking
│ │ ├── embedder.ts # Ollama client (+ a fake for tests)
│ │ ├── ranking.ts # Fusion, weights, per-note cap and env validation
│ │ ├── store.ts # pgvector schema, upserts, hybrid search
│ │ ├── scanner.ts # Vault walk and change detection
│ │ └── SearchService.ts # What the MCP tools call
│ ├── maintain/ # Report configuration, decisions, renderer and worker
│ ├── maintain.ts # Report-only maintenance CLI
│ ├── learn/ # Learn log, redaction, configuration and reports
│ ├── learn-report.ts # Read-only learn-report CLI
│ ├── eval/ # Golden validation, metrics and fixed ranking grid
│ ├── eval.ts # Read-only brain-eval CLI entry point
│ ├── indexer.ts # Indexer entry point (second container)
│ └── types/
│ └── index.ts # TypeScript type definitions
├── sql/001_schema.sql # Index schema (dimension substituted at start)
├── tests/ # Vitest unit tests
├── Dockerfile
├── docker-compose.yml
├── package.json
└── README.md
The optional measurement layer requires semantic search and is off by default. It records the three search tools (semantic-search, similar-notes, search-vault), successful reads (read-note, read-multiple-notes, read-section), explicit feedback and session start/close with client names. Sessions are the legacy SSE stream (GET /sse + /message) and, since 1.10.1, POST /sse clients: initialize returns an Mcp-Session-Id header, later requests that echo it are logged under that session, and DELETE /sse with the header closes it. POST /sse requests without the header are logged with client name post and no session. Search ranking is unchanged; search never reads these logs.
Set LEARN_LOG=true and LEARN_REDACT_PATTERNS_FILE to a readable UTF-8 file. Blank lines and comments are ignored, whitespace is trimmed, and each other line is a JavaScript regex source compiled case-insensitively. An example file is:
# comment
\bexample-term\b
Eight built-in patterns also detect private-key headers, access-key shapes, JWTs, hosted Git tokens, secret assignments, bearer credentials, URL token parameters and 64-character hex strings. Sensitive queries (including similar-note paths) and their embeddings are cleared before storage. Sensitive string parameters become [redacted]; sensitive feedback notes are cleared, sensitive feedback paths are dropped, and sensitive read paths are never logged. Site-specific patterns belong in the external file. An invalid configuration disables logging, never search, and is reported at startup.
Logged searches return an additive requestId. Pass it to a read's optional requestId argument, then call search-feedback with requestId, rating (positive, negative, neutral) and usedPaths. expectedPaths and a short note are optional. source defaults to agent; use user only for explicit human feedback. Unknown ids return { recorded: false, reason: 'unknown requestId' }. Reads with unknown ids are recorded without a link.
Search, read and session writes are fire and forget: they never delay tool responses and failures are logged with learn-log:. Feedback is awaited. The indexer loop applies retention at most daily, excluding --once. After LEARN_RETENTION_DAYS (default 30), query text, query embeddings and feedback notes are cleared. Paths, ranks, timestamps, checked parameters, client names and feedback paths remain. sql/002_learning.sql creates the four learn tables even when logging is off; the embedding column is recreated after a dimension reset. Keep learn-table data out of database dumps and exclude raw database files from backups when query retention is required.
Run the read-only report against an existing database:
node dist/learn-report.js --days 30 --out /existing-directory/learn-report.json
--days defaults to 30 (range 1–365); the output directory must already exist. It uses a read-only connection, ignores ranking and logging environment settings, and outputs counts and rates without query text. Stdout lists dotted keys in report order, followed by VOLUME GATE: pass|fail.
The report covers the selected collection and time window. Sessions include counts by client and the median closed duration in minutes. Searches include counts by tool and redacted share. Linked semantic reads use the minimum rank of the read path: usedAt1, usedAt3, usedAt8 are shares of linked reads, and missRate is the share absent from results. linkedSearchRate is the share of semantic searches with a linked read, and linkedSemanticPerDay is their daily count. Reformulation and fallback rates count session-linked semantic searches followed within 120 seconds by another semantic search or text search. Feedback coverage is the share of semantic searches with feedback; source counts and negative rates include all feedback. Zero-denominator rates and empty medians are null; numbers are rounded to four decimals. The volume gate passes at a rounded 30 linked semantic searches per day. Feedback from agents measures compliance; user corrections provide independent labels.
Off by default. Setting DATABASE_URL turns it on in both the server (four extra tools) and the indexer (a second process that keeps the index current). Everything runs locally: Postgres with the pgvector extension, and Ollama for embeddings.
--reindex).Title › H2 › H3). Chunk 0 is the title plus the frontmatter summary, so a one-line summary is the strongest signal for "which note answers this"..obsidian/, .trash/, .git/, Synology #recycle/ @eaDir/ @tmp/, AppleDouble ._*, dotfiles, non-.md files, any directory containing a .noindex file, and any note with frontmatter index: false.[[Areas/note]] resolves by path; [[note]] resolves if exactly one note in the vault has that basename, and stays unresolved (recorded, NULL target) when two do. Deleting one of two duplicates re-resolves the other the next time it is indexed.--reindex.brain-eval)Build with npm run build, then run with the same database, collection and embedding
configuration as the index:
node dist/eval.js --golden /private/golden.json --grid --out /private/runs/grid.json
# Or evaluate one configuration alongside the baseline:
node dist/eval.js --golden /private/golden.json --config '{"wText":1.5,"perNoteCap":2}' --out /private/runs/candidate.json
# npm run eval -- <the same arguments> also works.
The output directory must already exist. The CLI opens the database read-only: it never
applies schema changes, reindexes or writes to the index. The embedding model and dimension
must match the stored metadata, and every expected note must already exist in the collection.
Every query is embedded once and its vector reused across configurations. The fixed grid
contains 40 configurations, starting with the v1.8.0 baseline rrf-k60-v1-t1-cap0.
The CLI ignores ambient SEARCH_* ranking settings; --config merges only the supplied
fields over the baseline. Invalid ranking environment settings fail server startup.
Golden files are private evaluation data, with exactly these keys:
{
"version": 1,
"created": "2026-01-01",
"notes": "Synthetic example only",
"queries": [
{
"id": "example-1",
"category": "exact-id",
"query": "synthetic search phrase",
"expected": ["Example.md"]
}
]
}
Query ids must be unique, query strings non-empty, and expected lists non-empty with
unique .md paths. Categories are exact-id, paraphrase, decision-why, multi-hop,
and recent, reported in that order. Unknown keys are rejected. Keep golden sets and
evaluation reports outside a public code repository.
Metrics use unique note paths in result order, after requesting eight chunks:
mrr: mean reciprocal rank of the first expected note, or zero for a miss.recall5: a hit rate at 5, meaning any expected note in the first five notes.ndcg8: binary-relevance normalised discounted cumulative gain at eight notes.distinctNotes: mean number of distinct notes returned. Metrics are also broken down
by category, and the JSON report rounds them to four decimal places.A candidate must improve MRR by at least 0.0300, preserve every category's hit rate,
and preserve every query whose baseline hit was within five. Comparisons round metrics
to integer ten-thousandths. Passing candidates are ordered by higher MRR, hit rate, then
NDCG; ties prefer fewer changed ranking fields, then the lexicographically smaller id.
If none passes, the baseline wins with changed: false. The JSON includes the golden
file's SHA-256, per-query note lists, gate reasons, and the winning environment variables;
stdout prints the ranking table, category comparison and final WINNER line.
Exit codes: 0 for a completed report (including no ranking change), 2 for input
problems (arguments, golden validation, model mismatch or missing expected paths), and
1 for other runtime failures (database, embedding service or output writes).
Searches require pgvector 0.8.0 or newer: each transaction uses strict-order iterative
HNSW scans and filtered searches raise hnsw.ef_search to 100. Default RRF scores match
v1.8.0, with exact ties ordered by chunk position then id. DBSF scores range from zero
to the sum of the two leg weights.
---
title: ubuntubox — NFS mount gate # else first H1, else file name
type: area # filterable: semantic-search { type }
status: active # filterable: semantic-search { status }
tags: [infra, nas] # filterable: semantic-search { tags }
summary: One line that answers "what is this note about".
index: true # false = never indexed
---
Invalid frontmatter is reported, not hidden. A note whose --- block is not valid YAML (the usual cause is an unquoted value containing : , such as summary: Finished it: all done; quote it: summary: "Finished it: all done") is still indexed by its body, but without its metadata. The indexer logs WARN invalid frontmatter in <path>: <YAML error> when it indexes such a note and again at every start, each pass line carries invalid_frontmatter=<count>, and index-status returns invalidFrontmatter: { count, notes: [{ path, error }] } (first 20). reindex-note returns a warning. Fix the note and the flag clears on the next pass.
sql/001_schema.sql; nothing to run by hand. HNSW index builds need shared memory: give the Postgres container shm_size: 1g.ollama pull nomic-embed-text (768-d, 8k context) or bge-m3 (1024-d).DATABASE_URL, OLLAMA_URL, EMBED_MODEL (and optionally INDEX_COLLECTION) to the server's environment. The /health endpoint reports semanticSearch: enabled.command: ["node", "dist/indexer.js"], the same environment, and the vault mounted read-only. node dist/indexer.js --once --verbose does a single pass and exits non-zero if any file failed.services:
obsidian-mcp:
image: ghcr.io/smith-and-web/obsidian-mcp-server:latest
environment:
VAULT_PATH: /vault
API_KEY: ${API_KEY}
DATABASE_URL: postgres://brain:${DB_PASSWORD}@brain-db:5432/brain
OLLAMA_URL: http://ollama:11434
EMBED_MODEL: nomic-embed-text
INDEX_COLLECTION: secondbrain
volumes:
- /path/to/vault:/vault:rw
ports: ["127.0.0.1:3001:3000"]
obsidian-indexer:
image: ghcr.io/smith-and-web/obsidian-mcp-server:latest
command: ["node", "dist/indexer.js"]
environment:
VAULT_PATH: /vault
DATABASE_URL: postgres://brain:${DB_PASSWORD}@brain-db:5432/brain
OLLAMA_URL: http://ollama:11434
EMBED_MODEL: nomic-embed-text
INDEX_COLLECTION: secondbrain
INDEX_INTERVAL_SECONDS: "60"
volumes:
- /path/to/vault:/vault:ro
brain-db:
image: pgvector/pgvector:0.8.2-pg16
shm_size: 1g
environment:
POSTGRES_DB: brain
POSTGRES_USER: brain
POSTGRES_PASSWORD: ${DB_PASSWORD}
volumes:
- ./brain-db:/var/lib/postgresql/data
ollama:
image: ollama/ollama:latest
volumes:
- ./ollama:/root/.ollama
:ro.index: false or a .noindex directory).The server supports optional API key authentication. When API_KEY is set, all /sse and /message endpoints require authentication. The /health endpoint remains public.
Set the API_KEY environment variable:
# Docker
docker run -d \
--name obsidian-mcp \
-v /path/to/vault:/vault:rw \
-p 3001:3000 \
-e VAULT_PATH=/vault \
-e API_KEY=your-secret-key \
ghcr.io/smith-and-web/obsidian-mcp-server:latest
# npx
API_KEY=your-secret-key VAULT_PATH=/path/to/vault npx @smith-and-web/obsidian-mcp-server
Clients send the key in the Authorization header:
Authorization: Bearer your-secret-key
The ?api_key= query parameter was removed in 1.6.0 (it ends up in access logs and client history). Clients that used it must switch to the header, for example mcp-remote with --header "Authorization: Bearer your-secret-key".
Behind tailscale serve on loopback, set [email protected]. Requests then also need the Tailscale-User-Login header that serve adds for tailnet users; anything else gets 403. Do not rely on this if the port is reachable any other way, because the header can be forged by a direct client.
Claude Desktop / Cursor (via mcp-remote):
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://your-domain.com/sse",
"--header", "Authorization: Bearer your-secret-key"
]
}
}
}
Claude Code:
claude mcp add --transport sse obsidian https://your-domain.com/sse --header "Authorization: Bearer your-secret-key"
../../etc/passwd, are rejected; fixed in 1.4.1)127.0.0.1:3001:3000) unless remote access is intendedAuthorization header; the old ?api_key= query parameter was removed because URLs end up in access logsFor remote access with SSL:
Add a Proxy Host:
obsidian.yourdomain.comobsidian-mcp (container name)3000SSL Tab: Request Let's Encrypt certificate
Advanced Tab (for SSE):
proxy_buffering off;
proxy_cache off;
proxy_set_header Connection '';
proxy_http_version 1.1;
chunked_transfer_encoding off;
If your clients are on a Tailscale tailnet you can skip the public reverse proxy entirely. Keep the container on loopback and let tailscale serve publish it with a tailnet-only HTTPS certificate:
docker run -d --name obsidian-mcp -v /path/to/vault:/vault:rw -p 127.0.0.1:3001:3000 \
-e API_KEY=your-secret-key -e [email protected] \
ghcr.io/smith-and-web/obsidian-mcp-server:latest
sudo tailscale serve --bg --https=443 http://127.0.0.1:3001
Clients then use https://<machine>.<tailnet>.ts.net/sse with the Authorization: Bearer header. Never enable Tailscale Funnel for this server. See Tailscale login for what REQUIRE_TAILSCALE_LOGIN does and does not protect against.
# View logs
docker-compose logs -f obsidian-mcp
# Restart
docker-compose restart
# Rebuild
docker-compose up -d --build
# Check host mount
ls -la /path/to/your/vault
# Check container access
docker exec obsidian-mcp ls -la /vault
401 Unauthorized: missing or wrong Authorization: Bearer <key> header (the ?api_key= query parameter is no longer accepted).403 Forbidden: REQUIRE_TAILSCALE_LOGIN is set and the request did not arrive through tailscale serve as that user.Path escapes vault: the requested path resolves outside VAULT_PATH; use a path relative to the vault.summary, tags or type filters: check index-status for invalidFrontmatter (or the indexer log for WARN invalid frontmatter); the note's YAML is invalid and was indexed without its metadata.mcp-remote (the server has no stdio mode).# Clone and install
git clone https://github.com/smith-and-web/obsidian-mcp-server.git
cd obsidian-mcp-server
make install
# Run with example vault
make dev
# Test connection
make test-connection
Run make help to see all available commands:
Development:
make install Install dependencies
make dev Run server with hot-reload
make start Run server in production mode
make test-connection Test server connectivity
Docker:
make docker-build Build Docker image
make docker-up Start Docker container
make docker-down Stop Docker container
make docker-logs View container logs
make docker-restart Restart container
make docker-shell Open shell in container
The repository includes a Bruno collection for testing the core tools (the four semantic-search tools need DATABASE_URL and a running index).
./bruno/obsidian-mcplocal or remote environmentThe collection is organized by category:
health/ - Server health and tool listingnotes/ - Note CRUD operationsdirectories/ - Directory operationsfrontmatter/ - Frontmatter operationstags/ - Tag managementsearch/ - Search and find-replacelinks/ - Backlinks and broken linkssections/ - Section-based operationsAn example vault is included in ./examples/test-vault/ for development and testing. It includes sample notes with tags, links, and sections to test all features.
See CONTRIBUTING.md for guidelines.
MIT License - see LICENSE for details.
Run node dist/maintain.js (or npm run maintain) from the same image as the server, with DATABASE_URL, INDEX_COLLECTION, VAULT_PATH and MAINTAIN_REPORT_DIR configured. Schedule it weekly with your host's scheduler. --dry prints candidate counts and hygiene metrics without recording a run or writing a report. The index must already exist.
Seven deterministic checks find missing links, unlinked mentions, uniquely repairable unresolved links, missing index or aliases frontmatter, stale summaries, near-duplicates and stale project or area hubs. Notes with type journal or inbox are excluded as targets. Notes under Journal/ get no link suggestions in either direction. An unlinked mention counts only in a note's prose (not its frontmatter, first H1, code, wikilinks or markdown links) and only as a whole word, case-insensitively, with hyphens part of the word; the worker reads the source note from VAULT_PATH to check. Near-duplicate pairs skip notes that already link to each other and pairs of plan notes. The indexer records summary/body cosine history when content changes, and maintenance backfills baselines for older notes. Search ranking stays unchanged, and maintenance never reads learn tables.
Each ISO week produces Brain maintenance YYYY-Www.md in the configured output directory. Reports are draft notes with index: false, stable finding ids, accept/reject checkboxes, trends and acceptance counts. They stay out of search and the link graph. A rerun parses ticks first and atomically replaces only that week's report; moved reports are still discovered by their maintenance_report frontmatter.
Tick one checkbox per finding, or explicitly ask the assistant to call maintenance-decision with finding: "f17", decision: "accept" or "reject", and an optional reason. Conflicting ticks record no decision. A checkbox never overrides an earlier decision; an explicit tool call may change one. Rejected findings are never proposed again. Fixed findings resolve without counting as acceptance. New findings are capped per class, with at most 50 open findings listed in a report.
This stage is report-only: accepting records a decision and changes no note. Apply accepted findings yourself. Near-duplicate merges and hub reviews remain report-only permanently. The worker never edits existing notes; its only vault write is its own report.
recommend-notes takes 1–10 positive paths, up to 10 negative paths, an optional integer k (1–50), type and directory. It excludes the examples. best_score compares the nearest positive and negative; average_vector uses the positive mean, moved away from the negative mean when present. Neither tool requires learn logging; sensitive decision reasons are stored as null using the active redaction patterns or the built-ins.
MCP server for Obsidian vault management - enables Claude and other AI assistants to read, write, search, and organize your notes
Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Obsidian se ejecuta localmente por stdio.
Última comprobación: 2026-10-28. MCP server for Obsidian vault management - enables Claude and other AI assistants to read, write, search, and organize your notes