Local Computer MCP

Local Filesystem MCP is a small, dependency-free Model Context Protocol server written in Go. It gives a trusted local MCP client practical tools for finding, inspecting, organizing, converting, and safely modifying files on the machine where the server runs.

The server uses stdio transport. It does not expose a network listener, upload files, call an embedding service, or execute arbitrary shell commands.

What it does

Search and discovery

• find_file searches names, glob patterns, extensions, file types, modification dates, and bounded text prefixes.
• semantic_file_search ranks local matches across names, paths, and bounded readable text.
• find_download searches a platform Downloads directory inside the configured roots.
• recent_activity lists recently modified files and directories.
• find_duplicate_files groups same-sized files and confirms matches with SHA-256 hashing.
• file_info and list_directory provide portable metadata without recursive output flooding.

File and folder operations

• create_folder creates a directory tree.
• read_text_file reads a bounded UTF-8 slice.
• write_text_file writes through a temporary file and refuses collisions by default.
• rename_file, move_file, and copy_file support common file workflows.
• delete_path requires confirm=true and never deletes an allowed root.
• organize_folder previews moves by default and can organize by extension, date, or broad type.
• extract_archive supports ZIP, TAR, TAR.GZ, and TGZ with traversal, symlink, entry-count, and expansion-size protection.
• convert_file supports text/JSON, CSV/JSON, and Base64 conversions.

Local integrations

• inspect_clipboard reads text through fixed platform commands.
• search_browser_history reads copied Chrome, Edge, Brave, or Firefox SQLite history databases when sqlite3 is installed.
• memory_set, memory_get, memory_list, and memory_forget provide a bounded, locked JSON preference store.

Safety model

The server is designed for a trusted local MCP client. It has no authentication and must not be exposed as a public network service.

• The default allowed root is the current user's home directory. Set LOCAL_FILESYSTEM_MCP_ROOTS to narrow it.
• Every requested path and destination is canonicalized through its existing parent before use.
• Symbolic-link and Windows reparse-point traversal is rejected for direct paths and archive destinations.
• Configured roots are canonicalized and overlapping roots are compacted to prevent duplicate scans.
• Recursive searches do not follow symlinks and surface permission errors instead of silently claiming complete results.
• Search, read, archive, duplicate, memory, and response-producing operations have explicit bounds.
• organize_folder defaults to dry_run=true.
• Writes, copies, moves, and renames refuse collisions unless overwrite=true.
• delete_path requires both confirm=true and, for directories, recursive=true.
• Archive extraction stages a new destination before publishing it when possible, writes individual files atomically, and never materializes archive links or special device entries.
• Clipboard and browser-history adapters use fixed executable names and argument shapes; arbitrary shell strings are never evaluated.
• Persistent memory is stored in the operating system's application-config directory by default. This is an intentional internal state location and is separate from the file-operation roots.

No filesystem boundary can protect against a user who already has permission to modify the same directories concurrently. Run the server with the narrowest roots that fit the task.

Installation

Download a binary from the GitHub Releases page, or build locally with Go 1.22 or newer.

local-filesystem-mcp            Linux
local-filesystem-mcp            macOS
local-filesystem-mcp.exe        Windows

Verify an installation:

local-filesystem-mcp --version

Build from source

go test ./...
go vet ./...
go test -race ./...
go build -trimpath -ldflags "-s -w" -o bin/local-filesystem-mcp .

The project uses only the Go standard library.

MCP client configuration

Point the client at the binary. The environment variable is optional but strongly recommended.

Windows

{
  "mcpServers": {
    "local-filesystem": {
      "command": "C:\\Tools\\local-filesystem-mcp.exe",
      "args": [],
      "env": {
        "LOCAL_FILESYSTEM_MCP_ROOTS": "C:\\Users\\you\\Documents;C:\\Users\\you\\Downloads"
      }
    }
  }
}

macOS or Linux

{
  "mcpServers": {
    "local-filesystem": {
      "command": "/Users/you/bin/local-filesystem-mcp",
      "args": [],
      "env": {
        "LOCAL_FILESYSTEM_MCP_ROOTS": "/Users/you/Documents:/Users/you/Downloads"
      }
    }
  }
}

The roots value accepts the platform path-list separator. Semicolons are also accepted for convenient cross-platform configuration copying.

Configuration

All settings are optional.

Variable	Default	Purpose
LOCAL_FILESYSTEM_MCP_ROOTS	User home directory	Allowed filesystem roots
LOCAL_FILESYSTEM_MCP_MAX_RESULTS	100	Default result limit
LOCAL_FILESYSTEM_MCP_MAX_SCAN_FILES	200000	Maximum entries considered by a recursive scan
LOCAL_FILESYSTEM_MCP_MAX_READ_BYTES	4194304	Maximum bytes read from one text file or clipboard
LOCAL_FILESYSTEM_MCP_MAX_ARCHIVE_SIZE	2147483648	Maximum expanded archive bytes
LOCAL_FILESYSTEM_MCP_MAX_HASH_BYTES	8589934592	Maximum duplicate-search bytes hashed
LOCAL_FILESYSTEM_MCP_MAX_MEMORY_BYTES	8388608	Maximum persistent memory file size
LOCAL_FILESYSTEM_MCP_MEMORY_FILE	OS config directory	Override persistent memory path

Default memory locations are platform-aware:

• Windows: %APPDATA%\\local-filesystem-mcp\\memory.json
• macOS: ~/Library/Application Support/local-filesystem-mcp/memory.json
• Linux: ~/.config/local-filesystem-mcp/memory.json or the directory reported by Go

Transport and protocol

The process reads newline-delimited JSON-RPC 2.0 messages from stdin and writes responses to stdout. Logs go to stderr. It implements the MCP initialization lifecycle, tool discovery, tool calls, cancellation notifications, and graceful exit handling.

The executable is intentionally not a general-purpose file server and does not accept HTTP connections.

Platform integrations

Clipboard support uses:

• Windows: PowerShell Get-Clipboard
• macOS: pbpaste
• Linux and other Unix-like systems: wl-paste, xclip, or xsel

Browser history support requires the sqlite3 command-line utility. The database is copied before it is queried so an active browser database is not opened directly. Firefox profile discovery covers the standard Windows, macOS, and Linux profile locations.

Releases

Every push to main runs formatting, tests, vet, race checks, and a build check through GitHub Actions.

To publish binaries automatically:

git tag v0.2.0
git push origin v0.2.0

The release workflow builds Linux, macOS, and Windows binaries for amd64 and arm64, packages each binary with the README and MIT license, generates SHA-256 checksums, and attaches the artifacts to the GitHub Release.

Project layout

• main.go starts the signal-aware stdio server.
• protocol.go implements JSON-RPC/MCP lifecycle, validation, dispatch, and cancellation.
• config.go loads bounded environment configuration.
• paths.go contains canonical root confinement and symlink/reparse-point protection.
• operations.go contains filesystem, archive, and conversion operations.
• integrations.go contains clipboard, browser-history, duplicate, and recent-activity adapters.
• memory.go contains the bounded persistent JSON memory store.
• memory_lock_unix.go and memory_lock_windows.go provide cross-process memory locking.
• util.go contains shared parsing, walking, hashing, and context helpers.
• server_test.go contains protocol, security-boundary, archive, search, conversion, and persistence regression tests.