Strayfiles MCP: Let AI Agents Manage Your Notes

You’re in a Claude Code session. You need to find that note you wrote about the caching strategy. You know it’s somewhere — maybe in the project docs, maybe in your personal notes folder. You open a new terminal tab, run find, scroll through results, open the file, copy the relevant section, paste it back into the conversation.

That context switch just cost you 2 minutes and broke your flow.

The MCP Server

We built the Strayfiles MCP server so AI agents can work with your notes directly. No more copying and pasting between terminals. No more “let me check my notes” interruptions. Your agent reads, writes, and organizes your markdown files as part of the conversation.

43 Tools, One Protocol

The MCP server exposes 43 tools across 9 categories. Your agent gets the same capabilities as the TUI and native apps:

Category	Count	Examples
Notes	10	Read, create, edit, delete, rename, move, alias, pin
Search & Discovery	3	Search by name/tag/workspace, discover untracked files, track files
Directories	5	Create and manage folder structure
Tags	6	Full CRUD plus tag/untag notes
Workspaces	6	Virtual organization without moving files
Mirrors	5	One-way file sync between locations
Version History	4	Browse, diff, and restore previous versions
Conflicts	3	Detect, inspect, and resolve sync conflicts
Devices	1	Multi-device mapping

All tools operate on real .md files on disk. The database stores only metadata. Your notes are always accessible with any editor, syncable with Git or iCloud, and readable without Strayfiles installed.

Discovery: The Killer Workflow

Most developers accumulate markdown files without a system. CLAUDE.md here, README.md there, project notes scattered across a dozen directories.

The discovery workflow fixes this in one conversation:

You: "Scan ~/projects for all CLAUDE.md and README.md files,
      track them, and organize by project."

Claude: *scans filesystem*
        "Found 23 untracked files across 9 projects.
        I'll use frontmatter for CLAUDE.md files and
        HTML comments for READMEs."

        *tracks all 23 files*
        *creates a workspace per project*
        *assigns notes to matching workspaces*

Claude: "Done. 23 files organized into 9 workspaces.
        You can now search across all of them."

No manual file management. No import wizards. Your agent handles the entire setup while you focus on actual work.

Version History and Conflict Resolution

Every edit through MCP creates a version snapshot. Your agent can diff changes, browse history, and restore previous versions — useful when you realize yesterday’s version of your architecture notes was better.

Conflicts from multi-device sync are surfaced as tools too. Your agent can inspect both versions, explain the differences, and resolve with your preferred strategy: keep local, keep remote, or auto-merge.

Why Not an Obsidian MCP?

Obsidian just shipped an official CLI and there are several Obsidian MCP servers available. They’re good tools — if all your notes live in an Obsidian vault.

But that’s the constraint. Obsidian MCP servers operate on a vault: a single folder that Obsidian owns. Your CLAUDE.md in a repo, your README.md in another project, your scratch notes in a different directory — they’re either in the vault or they don’t exist.

Strayfiles doesn’t have a vault. It has your filesystem.

Your agent can discover files across ~/projects, ~/work, and ~/notes in one scan. Track a CLAUDE.md inside a Git repo without moving it. Organize files from 12 different directories into virtual workspaces — without copying a single byte. The metadata layer is optional frontmatter that other tools ignore completely.

The Obsidian approach: move your files into our system. The Strayfiles approach: we’ll adapt to yours.

Works with Every MCP Client

The server supports any client that speaks the Model Context Protocol:

• Claude Code — Plugin or direct MCP add
• Cursor — Add to ~/.cursor/mcp.json
• Windsurf — Add to Windsurf MCP config
• OpenAI Codex — codex mcp add
• VS Code — Add to .vscode/mcp.json
• Zed — Add to Zed settings

For Claude Code users, the plugin includes skill definitions that teach the agent common workflows — so it knows how to chain tools effectively without you spelling out every step.

Open Source

The plugin and MCP wrapper are MIT licensed:

• Plugin: github.com/titofebus/strayfiles-mcp
• npm: npx -y strayfiles-mcp

Contributions welcome. See CONTRIBUTING.md.

Get Started

# Install the plugin (Claude Code)
claude plugin install https://github.com/titofebus/strayfiles-mcp.git

# Or add to any MCP client
npx -y strayfiles-mcp

# Install the Strayfiles binary (if not already installed)
curl -fsSL https://strayfiles.com/install.sh | sh

Then tell your agent what you need. It has your notes now.

Read the full documentation at strayfiles.com/docs/guides/mcp.