Obsidian MCP server — a setup that survives a second developer

On this page#

• What the integration actually does
• The wiring
• The two things that break it
• Verifying it works
• Team considerations
• FAQ

What the integration actually does#

An Obsidian MCP server does not “put your vault inside the agent.” It exposes selected operations—typically listing, searching, reading, and sometimes writing notes—through a protocol the agent can call. Obsidian remains the editor, the vault remains ordinary files, and the server becomes a controlled bridge between those files and the agent.

MCP, the Model Context Protocol, defines how an AI client discovers and invokes external tools or resources. The useful mental model is not “Obsidian plugin.” It is “a local process with access to some Markdown files.”

| What people assume | What actually happens | |---|---| | The agent automatically understands the whole vault | It receives only the content returned by specific MCP calls | | Obsidian grants and manages access | The server process gets access through its filesystem permissions and configuration | | MCP adds durable memory | Notes are durable; the agent’s interpretation is still request-scoped | | A successful connection means the setup is safe | It only proves the client can talk to the server | | Every Obsidian MCP server behaves the same | Tool names, write behavior, path handling, and configuration vary by implementation |

The MCP architecture separates the host, client, and server. That separation matters operationally: your coding agent is the host, its MCP client manages the connection, and the Obsidian-facing server performs the file operations.

Do not point the server at your entire personal vault because it is convenient. That is the wrong default for a real repository. Create a narrow, repository-relevant knowledge area containing architecture decisions, runbooks, domain notes, and investigation records the agent is genuinely allowed to read.

Photo by cottonbro studio on Pexels.

The wiring#

The durable setup is a repository-owned client configuration, a pinned server dependency, and an explicitly scoped vault path. Keep machine-specific paths out of the committed file. If the second developer must edit JSON before the first connection, the configuration is not team-ready.

Because Obsidian MCP implementations use different package names, flags, and environment variables, the configuration below deliberately marks implementation-specific values. Replace those fields with the exact equivalents documented by the server you selected; do not silently assume that a generic --read-only flag exists.

1. Create a repository-specific vault directory or choose a narrow existing subdirectory.

repo/
├── .mcp.json
├── docs/
│   └── knowledge/
│       ├── architecture/
│       ├── decisions/
│       └── runbooks/
└── tools/
    └── start-obsidian-mcp

A directory inside the repository is the simplest team option because its path and contents can follow the repository’s normal review rules. If the notes must remain in an external Obsidian vault, expose only a dedicated subdirectory and supply its absolute path locally.

2. Commit the client configuration.

{
  "mcpServers": {
    "obsidian": {
      "command": "./tools/start-obsidian-mcp",
      "args": [],
      "env": {
        "OBSIDIAN_MCP_ROOT": "./docs/knowledge",
        "OBSIDIAN_MCP_ACCESS": "read-only"
      }
    }
  }
}

The filename and outer key can differ between Claude Code, Codex, Cursor, and other hosts. Preserve the same contract even when their syntax differs: one named server, one repository-owned launcher, one scoped root, and read-only access by default.

The official MCP reference-server repository is useful for understanding server structure, but reference implementations are not a reason to leave dependency versions floating. A team configuration must resolve to the same server code for both developers.

3. Make the launcher the only implementation-specific boundary.

#!/bin/sh
set -eu

: "${OBSIDIAN_MCP_ROOT:?OBSIDIAN_MCP_ROOT is required}"

exec npx --yes "<SERVER_PACKAGE>@<PINNED_VERSION>" \
  "<ROOT_FLAG>" "$OBSIDIAN_MCP_ROOT" \
  "<READ_ONLY_FLAG>"

Replace the three angle-bracket placeholders before use. If your chosen implementation configures access through environment variables rather than flags, translate the contract there. The important part is that client configurations do not duplicate a fragile launch command.

4. Keep local overrides uncommitted when an external vault is unavoidable.

{
  "env": {
    "OBSIDIAN_MCP_ROOT": "/absolute/local/path/to/vault/team-knowledge",
    "OBSIDIAN_MCP_ACCESS": "read-only"
  }
}

Commit an example containing a placeholder, never one developer’s home-directory path. Also keep credentials out of both the vault and MCP configuration. Filesystem access is not a secret-management strategy.

5. Enable writes only for a separate, narrow server entry.

{
  "mcpServers": {
    "obsidian-read": {
      "command": "./tools/start-obsidian-mcp",
      "env": {
        "OBSIDIAN_MCP_ROOT": "./docs/knowledge",
        "OBSIDIAN_MCP_ACCESS": "read-only"
      }
    },
    "obsidian-drafts": {
      "command": "./tools/start-obsidian-mcp",
      "env": {
        "OBSIDIAN_MCP_ROOT": "./docs/knowledge/drafts",
        "OBSIDIAN_MCP_ACCESS": "read-write"
      }
    }
  }
}

Do not grant write access to the whole vault merely because the server offers write tools. A dedicated drafts directory makes agent-created material visible, reviewable, and disposable without weakening the rest of the knowledge base.

For a broader repository operating model around permissions, handoffs, and agent instructions, the Agent Operating Kit is the natural next layer. The MCP connection is only one boundary in that system.

The two things that break it#

Nearly every failed setup belongs to one of two categories: the client cannot start the server process, or the process starts with the wrong filesystem boundary. Diagnose those separately. Reinstalling packages will not fix an incorrect vault path, and changing permissions will not fix a missing executable.

1. The server process never starts#

The visible errors are usually variations of ENOENT, command not found, spawn failed, or “server disconnected.” They mean the host could not locate the command, the launcher was not executable, the working directory was unexpected, or the server wrote invalid output to the protocol stream.

Fix the launch boundary:

• Use a repository-relative launcher instead of a shell alias.
• Pin the server dependency.
• Ensure the launcher is executable on supported systems.
• Send diagnostic logs to standard error, not standard output.
• Confirm the agent starts from the repository root.
• Restart the host after changing its MCP configuration.

MCP commonly uses a local process transport in which protocol messages travel through the child process. The architecture documentation explains why unsolicited standard-output logging can corrupt that conversation.

2. The server starts against the wrong root#

The common symptoms are an empty search result, permission denied, path not found, or—more dangerously—successful access to unrelated notes. The last case is not a successful setup. It is a scope failure.

Fix the filesystem boundary:

• Resolve the configured root from a documented working directory.
• Prefer a repository-relative path when possible.
• For external vaults, use a local absolute-path override.
• Check operating-system permissions for the process running the agent.
• Reject traversal outside the configured root.
• Keep read-only and read-write roots separate.

A broad root plus a prompt saying “only read project notes” is not access control. Prompts guide behavior; process and filesystem boundaries constrain capability.

Photo by Daniil Komov on Pexels.

Verifying it works#

A real verification checks discovery, one known read, one known miss, and one forbidden write. Seeing the server name in a settings panel proves only that configuration was parsed. It does not prove the correct process, directory, permissions, or content boundary is active.

Use a small canary note:

# MCP verification

Repository: current
Purpose: confirm scoped read access

Then run this acceptance sequence through the agent:

1. Ask it to list the Obsidian server’s available tools or resources.
2. Ask it to find MCP verification.
3. Ask it to return the note’s exact Repository and Purpose fields.
4. Ask for a deliberately nonexistent note and require a clean “not found” result.
5. Ask the read-only server to create should-not-exist.md; the operation must be unavailable or denied.
6. Confirm manually that no file was created outside the permitted root.

The MCP specification defines protocol interoperability, not your repository’s acceptance criteria. Your test must verify the boundary you intended to create.

Document this sequence in the repository. If you are still establishing basic agent workflows, use PairFoundry’s free foundations track. Related implementation patterns also live in Wiring It In.

Team considerations#

The second developer will expose every hidden assumption: local paths, global packages, unpinned versions, undocumented approval prompts, and private notes treated as shared context. A maintainable integration makes those assumptions explicit in the repository and gives a new machine one short, deterministic verification path.

Ship these items together:

• A committed client configuration or supported examples for each agent host.
• One launcher that owns the implementation-specific command.
• A pinned dependency identifier.
• A sample local override for external vault paths.
• A documented read-only default.
• A separate writable drafts root, if writes are necessary.
• The six-step acceptance check above.
• A clear rule for which notes may be committed.

Also decide ownership. Someone must review server upgrades, permission changes, and new tool exposure. “Every developer manages their own MCP setup” sounds flexible, but it creates different capabilities under the same repository instructions.

If the team needs packaged guidance beyond this integration, compare the available options on the PairFoundry packs overview. The important standard is simple: a second developer should reproduce the boundary, not merely reproduce a green connection indicator.

Photo by panumas nikhomkhai on Pexels.

Related reading#

• Claude Code IntelliJ — a setup that survives a second developer
• Getting Claude Code Slack right the first time

FAQ#

Does Obsidian have an MCP server?#

Obsidian can be connected through third-party or custom MCP server implementations, but MCP itself is the protocol, not an Obsidian-owned server product. Evaluate the specific implementation’s tools, path controls, write behavior, and maintenance model before attaching it to a real vault.

What’s the best MCP server?#

The best server is the smallest maintained implementation that exposes the operations you need and lets you enforce a narrow root. More tools are not automatically better. For repository work, predictable startup, pinned dependencies, read-only operation, and explicit path boundaries matter more than a long feature list.

Is MCP server like LangChain?#

No. An MCP server exposes tools or resources through a standard client-server protocol. LangChain is an application framework for composing model workflows. A framework may use MCP, but they solve different problems and should not be treated as interchangeable layers.

How do I enable MCP server?#

Add the server process to your agent host’s MCP configuration, point it at a narrowly scoped vault directory, restart the host, and run the acceptance sequence above. Do not stop after the server appears connected; verify a known read, a known miss, and a denied write.