Go to homepage strayfiles
Back to docs
guides

MCP Server

Add the MCP server to Claude Code:

claude mcp add --transport stdio strayfiles -- npx -y strayfiles-mcp
Copied!

Give Your AI Agent Full Access to Your Notes

You’re deep in a coding session. You need to check the notes you wrote last week about that API design. Or you want Claude to update your project CLAUDE.md. Or you’ve got 50 scattered markdown files and want an agent to organize them.

The Strayfiles MCP server gives AI coding agents direct access to your notes. 43 tools for reading, writing, searching, organizing, and syncing markdown files — all through the Model Context Protocol.

How It Works

You: "Find all my CLAUDE.md files and add them to a workspace called 'ai-context'"

Claude: *discovers 12 CLAUDE.md files across your projects*
        *tracks each one with frontmatter injection*
        *creates 'ai-context' workspace*
        *assigns all 12 notes*

Claude: "Done. I found and organized 12 CLAUDE.md files into
        the 'ai-context' workspace. You can filter by this
        workspace anytime."

The MCP server wraps the Strayfiles engine. Your agent gets the same capabilities as the TUI and native apps — create notes, edit content, manage tags and workspaces, browse version history, resolve conflicts — all without leaving the conversation.

Available Tools

43 tools organized into 9 categories:

CategoryToolsWhat They Do
Notes10List, read, create, edit, delete, rename, move, get metadata, set alias, toggle pin
Search & Discovery3Search notes by name/tag/workspace, discover untracked files on disk, track files with frontmatter/HTML/TOML
Directories5List, create, rename, delete, move directories
Tags6Create, list, rename, delete tags; tag and untag notes
Workspaces6Create, list, rename, delete workspaces; assign and unassign notes
Mirrors5Set up one-way file mirrors, sync content, update paths, delete mirrors
Version History4List versions, read a specific version, diff between versions, restore
Conflicts3List unresolved conflicts, inspect conflict details, resolve with strategy
Devices1List registered devices for multi-device sync

No Vault Required

Unlike Obsidian MCP servers that require notes to live inside a vault folder, Strayfiles works with files wherever they are. Your CLAUDE.md stays in your repo. Your README.md stays in its project. Your scratch notes stay in your notes folder. The agent discovers and tracks them in place — no moving, no copying, no importing.

Discovery and Tracking

The most powerful workflow starts with discovery. Your agent can scan your filesystem for markdown files and start tracking them:

You: "Scan ~/projects for any CLAUDE.md or README.md files I'm not tracking yet"

Claude: discover_files(
          path="~/projects",
          pattern="**/CLAUDE.md",
          pattern="**/README.md"
        )

Claude: "Found 8 untracked files. Want me to track them?
        I'll use frontmatter for CLAUDE.md files and
        HTML comments for READMEs (so the metadata stays
        invisible in rendered markdown)."

Three tracking methods are available through MCP:

  • Frontmatter — Injects a UUID in YAML frontmatter. Survives renames and moves.
  • HTML comment — Invisible <!-- strayfiles: {...} --> comment. Ideal for README files.
  • TOML config — Adds path to strayfiles.toml. No file modification.

Version History Through MCP

Every edit creates a version snapshot. Your agent can browse history, diff changes, and restore previous versions:

You: "What changed in my API notes over the last few edits?"

Claude: list_note_versions(note_id="...")
        diff_note_versions(note_id="...",
                          version_a=3, version_b=5)

Claude: "Between version 3 and 5, you added the rate
        limiting section and rewrote the auth flow.
        Want me to restore version 3?"

Conflict Resolution

When notes are synced across devices, conflicts can occur. Your agent can inspect and resolve them:

Claude: list_conflicts()

Claude: "There's a conflict on 'architecture.md'. Your laptop
        version added a caching section. Your desktop version
        rewrote the database layer. Want me to merge both
        changes, keep one version, or let you decide?"

Resolution strategies: keep local, keep remote, or auto-merge (3-way merge).

Setting Up the MCP Server

The MCP server works with any MCP-compatible AI coding agent.

Claude Code

Add the MCP server:

claude mcp add --transport stdio strayfiles -- npx -y strayfiles-mcp

Or install as a plugin (includes skills and session hooks):

claude plugin install https://github.com/titofebus/strayfiles-mcp.git

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "strayfiles": {
      "command": "npx",
      "args": ["-y", "strayfiles-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "strayfiles": {
      "command": "npx",
      "args": ["-y", "strayfiles-mcp"]
    }
  }
}

OpenAI Codex

codex mcp add strayfiles -- npx -y strayfiles-mcp

Zed

Add to your Zed settings:

{
  "context_servers": {
    "strayfiles": {
      "command": "npx",
      "args": ["-y", "strayfiles-mcp"]
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "strayfiles": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "strayfiles-mcp"]
    }
  }
}

Auto-Configure

If you have the strayfiles binary installed, auto-detect and configure all installed clients:

strayfiles mcp setup          # auto-detect all installed clients
strayfiles mcp setup claude   # configure Claude Code only
strayfiles mcp setup cursor   # configure Cursor only
strayfiles mcp status         # show which clients are configured

Authentication (Optional)

strayfiles mcp is local-first and works without logging in.

If you want to link your Strayfiles account session:

strayfiles mcp auth    # browser token flow + online verification
strayfiles mcp status  # client setup + auth status
strayfiles mcp logout  # clear stored credentials

Binary Resolution

The npm wrapper (npx -y strayfiles-mcp) locates the strayfiles binary automatically:

  1. strayfiles in your PATH
  2. ~/.strayfiles/bin/strayfiles (cached download)
  3. ~/.local/bin/strayfiles (default install location)
  4. Auto-download from Strayfiles releases (with SHA-256 verification)

To install the binary manually:

curl -fsSL https://strayfiles.com/install.sh | sh

This installs only the strayfiles CLI/TUI binary used by MCP (not the full macOS app bundle or DMG).

Important Notes

Database lock: Strayfiles uses an exclusive database lock. If the TUI is running, close it before using MCP tools. Only one client can access the database at a time.

File-first: Notes are real .md files on disk. The database stores only metadata (IDs, names, timestamps, tags, workspaces). When you edit a note through MCP, you’re editing the actual file.

Edit is replace: edit_note replaces the entire file content. Agents will typically read the note first, make changes, then write back the full content. The tool supports optimistic concurrency with expected_version to prevent overwrites.

Combining MCP with Ping

The Strayfiles MCP server pairs well with Ping. Kick off a large organization task and get notified when it finishes:

You: "Scan all my projects for markdown files, organize them
      into workspaces by project, and ping me when done."

Claude: *discovers 47 files across 12 projects*
        *creates workspaces for each project*
        *assigns notes to workspaces*
        *pings you when finished*

Install both plugins:

claude plugin install https://github.com/titofebus/strayfiles-mcp.git
claude plugin install https://github.com/titofebus/strayfiles-ping.git

Troubleshooting

“Database is locked”

  • Close the Strayfiles TUI before using MCP tools
  • Only one client can hold the database lock at a time
  • If the lock is stale, restart the MCP server

“strayfiles binary not found”

  • Install manually: curl -fsSL https://strayfiles.com/install.sh | sh
  • Verify: strayfiles --version
  • Make sure ~/.local/bin is in your PATH

“Tools not appearing in my agent”

  • Restart your agent after adding the MCP server
  • Verify the config: strayfiles mcp status
  • Check that the binary starts: strayfiles mcp

“Note content is empty after create”

  • Pass content in the create_note call
  • If content was provided but is missing, check the file path in the note’s device mapping

“Version conflict on edit”

  • Another client edited the note since you last read it
  • Read the note again to get the current version
  • Re-apply your changes and retry with the new expected_version

Requirements

  • Strayfiles binary installed (curl -fsSL https://strayfiles.com/install.sh | sh)
  • Any MCP-compatible agent: Claude Code, Cursor, Windsurf, Codex, VS Code, Zed
  • macOS (Apple Silicon, Intel) or Linux (x64, arm64)
  • Node.js 18+ (for the npx wrapper) — not needed if using the binary directly