convez.ai
MCP ServerIntegração & APIsAvançado
ZhengchenTao

Obsidian MCP Server

ZhengchenTao/obsidian-mcp

Acesse e edite seu Obsidian pelo Claude com segurança OAuth

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta o Claude ao seu vault Obsidian, permitindo leitura e escrita de notas com autenticação segura via OAuth 2.1 + JWT. Suporta HS256 e RS256, funciona com qualquer provedor OAuth padrão (Auth0, Keycloak, Logto, ZITADEL) e implementa controle de acesso granular via blacklist de caminhos.

Instalação

$npx convez-ai ZhengchenTao/obsidian-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Integrar vault Obsidian como contexto em conversas com Claude
  • Automatizar escrita e atualização de notas via MCP
  • Sincronizar pesquisa e conteúdo entre Obsidian e fluxos de IA

Veredito

Solução robusta e production-ready para integração Obsidian-Claude com autenticação OAuth profissional. Recomendado para quem já opera infraestrutura de identidade ou busca controle fino sobre acesso a notas sensíveis.

README

A tradução para o português deste README ainda está na fila.

obsidian-mcp

English | 简体中文

Read and write an Obsidian vault via MCP (Model Context Protocol), gated by OAuth-issued JWT bearer tokens.

This server pairs with any OAuth 2.1 + PKCE authorization server that can mint JWTs containing aud, iss, sub, scope claims. Two signing modes:

  • HS256 (default) — shared symmetric key between AS and this server. Use for self-built minimal AS.
  • RS256 — fetches JWKS automatically via OIDC discovery from <Issuer>/.well-known/openid-configuration. Use with any standard provider: Logto, ZITADEL, Keycloak, Auth0, etc.

See Choosing an AS below for setup guidance.

Architecture

MCP client (Claude.ai, etc.)
    │
    │ ① GET /.well-known/oauth-authorization-server  (RFC 8414)
    │ ② OAuth Authorization Code + PKCE  (against your AS)
    │ ③ Bearer JWT (aud=obsidian, scope=read:obsidian | write:obsidian)
    │
    ▼
obsidian-mcp /mcp
    │  JWT verify (HS256, shared key with AS)
    │  VaultPathResolver — chroot + blacklist (gates reads and writes alike)
    │
    ▼
/vault  (any mounted directory — local folder / WebDAV / NFS / SMB sync target.
         the server only reads & writes local paths; it does not speak any sync protocol.)

MCP tools

ToolScope requiredDescription
list_vault_treeread:obsidianDepth-limited directory tree of the vault
list_filesread:obsidianFiles and subdirs in a directory
read_fileread:obsidianFile content (UTF-8), with optional byte-range params
searchread:obsidianLiteral substring search, glob-filterable
get_metadataread:obsidianSize, modified_at, has_frontmatter
write_filewrite:obsidianOverwrite any file outside the blacklist
append_filewrite:obsidianAppend to any file outside the blacklist

Configuration

All settings are bound from configuration with Vault__, Jwt__, Mcp__OAuthDiscovery__ prefixes (double underscore = nested section). Production values must be injected via env vars.

VariableDefaultRequiredDescription
Vault__Root/vaultyesVault root directory inside the container
Vault__Blacklist__0—noExtra path segments to deny for both reads and writes (.obsidian, .trash, .git are always denied)
Jwt__AlgorithmHS256noHS256 or RS256
Jwt__Issuer—yesExpected iss claim — your AS's issuer URL
Jwt__AudienceobsidiannoExpected aud claim
Jwt__SigningKey__Current—HS256 onlyHS256 signing key, shared with your AS
Jwt__SigningKey__Previous—noPrevious HS256 key during rotation window
Mcp__OAuthDiscovery__Issuer—yes/.well-known/oauth-authorization-server issuer field
Mcp__OAuthDiscovery__AuthorizationEndpoint—yesYour AS's /authorize URL
Mcp__OAuthDiscovery__TokenEndpoint—yesYour AS's /token URL
Mcp__OAuthDiscovery__RegistrationEndpoint—noYour AS's /register URL (DCR)
Mcp__OAuthDiscovery__ResourceUrlrequest hostnoRFC 9728 resource identifier for this MCP server
AuditLog__Directory/app/logsnoDirectory for audit log files
ASPNETCORE_ENVIRONMENTProductionnoDevelopment for verbose logs

Write access

Writes (write_file / append_file) are allowed anywhere reads are: the only gate is Vault__Blacklist plus path-safety (no traversal, no absolute paths, no symlinks). To keep a directory fully off-limits for both reads and writes — e.g. a secrets folder — add its segment to Vault__Blacklist__N.

Local development

# 1. Create a test vault
mkdir -p test-vault/Notes
echo "# Test" > test-vault/Notes/test.md

# 2. Set required env vars
export Vault__Root=./test-vault
export Jwt__Issuer=https://your-auth-server.example.com
export Jwt__Audience=obsidian
export Jwt__SigningKey__Current=dev-secret-key-at-least-32-chars-long
export Mcp__OAuthDiscovery__Issuer=https://your-auth-server.example.com
export Mcp__OAuthDiscovery__AuthorizationEndpoint=https://your-auth-server.example.com/authorize
export Mcp__OAuthDiscovery__TokenEndpoint=https://your-auth-server.example.com/token

# 3. Run
dotnet run

# 4. Generate a test JWT (requires dotnet user-jwts)
dotnet user-jwts create \
    --issuer https://your-auth-server.example.com \
    --audience obsidian \
    --name tester \
    --claim sub=tester \
    --claim scope="read:obsidian write:obsidian"

# 5. Test with MCP Inspector
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL: http://localhost:5000/mcp
# Bearer Token: <paste JWT from step 4>

Docker

A multi-stage Dockerfile is included. Build locally with:

docker build -t obsidian-mcp .

Run with a mounted vault:

docker run --rm -p 8080:8080 \
  -v /path/to/vault:/vault \
  -e Jwt__Issuer=https://your-auth-server.example.com \
  -e Jwt__SigningKey__Current=$JWT_SIGNING_KEY \
  -e Mcp__OAuthDiscovery__Issuer=https://your-auth-server.example.com \
  -e Mcp__OAuthDiscovery__AuthorizationEndpoint=https://your-auth-server.example.com/authorize \
  -e Mcp__OAuthDiscovery__TokenEndpoint=https://your-auth-server.example.com/token \
  -e Vault__Blacklist__0=01-Secret \
  obsidian-mcp

The included .gitea/workflows/build-image.yml is a Gitea Actions workflow that builds and pushes the image, then optionally redeploys the container on the runner host (controlled by vars.DEPLOY_PATH, see below). It expects these repository Variables / Secrets:

  • vars.REGISTRY — registry hostname (e.g. ghcr.io, or git.example.com for Gitea Container Registry)
  • vars.IMAGE_OWNER — registry owner/namespace
  • secrets.PACKAGES_TOKEN — registry push token
  • vars.DEPLOY_PATH — (optional) path to a docker-compose directory on the runner host. When set, the workflow runs a follow-up deploy job that cds into this directory and docker compose up -d to pull the new image. Leave empty to only build & push.

Choosing an AS

Claude.ai chat enforces the full OAuth Authorization Code + PKCE flow against your MCP server's /.well-known/oauth-authorization-server endpoint — there is no bearer-token shortcut. Pick one of these paths:

Hosted (fastest start, recommended for new setups) — RS256 mode:

ProviderFree tierNotes
Logto Cloud5000 MAULightest, ~30 min setup
ZITADEL Cloud25k auths/monthMore featureful, slightly heavier docs

Set Jwt__Algorithm=RS256 and Jwt__Issuer=<your-tenant-issuer-URL>. Public keys are fetched automatically from <Issuer>/.well-known/openid-configuration.

Self-hosted, full-featured — RS256 mode: Keycloak, ZITADEL, Logto, Authentik.

Self-hosted, minimal — HS256 mode: See nas-auth — the reference ~500 LoC AS this server was developed against. Or write your own. The MCP server's Jwt__SigningKey__Current and the AS's signing key must match.

Required AS features regardless of choice:

  • OAuth 2.1 + PKCE (RFC 7636)
  • Dynamic Client Registration (RFC 7591) — so Claude.ai can self-register
  • resource parameter support (RFC 8707) — for audience-bound tokens
  • Custom scope support (read:obsidian, write:obsidian)

Running tests

cd obsidian-mcp.Tests
dotnet test

License

MIT

Ver o original no GitHub

Bom para

Relacionados