K Filesystem MCP

English | 中文

K Filesystem MCP is a K edition of the official MCP filesystem server, tuned for Codex-style local development workflows.

It keeps the general purpose of @modelcontextprotocol/server-filesystem, then adds faster high-frequency file operations, bounded output, structured status fields, safer edit/write behavior, and clearer tool descriptions so coding agents can choose the right filesystem tool with fewer retries.

Security Warning

This server runs in global local filesystem mode. It can read, write, copy, move, and remove any file that the current OS user can access.

Use it only in trusted local environments. Do not expose it to remote clients, shared machines, or untrusted users.

Related MCP server: parecode

What This Edition Optimizes

• Fewer shell/PowerShell calls for common filesystem work.

• Smaller context usage through range reads, compact output, structured summaries, bounded diffs, and long-line guards.

• Fewer failed edit attempts through exact ranges, anchor-based edits, stable error codes, and concise edit diagnostics.

• Safer mutations through overwrite guards, deletion previews, recursive deletion bounds, optional backups, newline/BOM preservation, and dry-run support where risk justifies it.

• Better broad search behavior through rg-backed search modes, sharded continuation, partial-shard reporting, and explicit hidden/ignored/symlink coverage flags.

Main Tools

• read_text_file: read known text files with head, tail, start_line / end_line, line numbers, output bounds, and selection metadata.

• read_multiple_files: batch reads for known files or ranges, with per-file success/error metadata.

• search_files: find paths with glob, depth, hidden/no-ignore/symlink flags, compact output, and result summaries.

• search_text: search file contents with output modes, context controls, type filters, max match length, sharded continuation, and rg-backed fast paths.

• list_directory, list_directory_with_sizes, directory_tree: bounded directory browsing, size-aware listing, and stable visual tree output.

• get_file_info, get_multiple_file_info: structured metadata for one or many paths.

• diff_text_files: bounded unified diffs for two local text files.

• edit_file: exact edits, ranged edits, anchor edits, top-level single-edit shortcuts, original-range batch application, and structured diagnostics.

• write_file: create files or intentionally replace whole files with overwrite guards, bounded diffs, optional backups, and newline/BOM handling.

• copy_path, move_file, remove_path: guarded copy, move, and deletion tools with structured preflight/status fields.

• read_media_file: bounded base64 reads for local images or audio.

Install

Clone or copy this repository, then install runtime dependencies:

npm install

The release includes dist/, so no build step is required for normal use.

Start

On Windows:

k-mcp-server-filesystem.cmd

The script launches:

node dist\index.js

You can also launch it directly from the repository root:

node dist\index.js

Codex Configuration

Configure Codex to start this server as an MCP named something like fs_k, then add a workspace rule that prefers mcp__fs_k for filesystem work.

A minimal rule is provided in:

• examples/AGENTS.example.md

• examples/k-filesystem-mcp-rule.example.md

The important routing idea is simple:

• Use K MCP for reads, searches, listings, metadata, diffs, edits, writes, copies, moves, and removals when a matching tool exists.

• Use shell/PowerShell for builds, scripts, dynamic generation, process inspection, syntax checks, and work outside MCP capabilities.

• Use dryRun: true for risky writes, recursive deletion, broad/ambiguous edits, and important user/project data; skip it for clear low-risk exact edits.

edit_file Notes

edit_file is designed to reduce the common "patch context did not match, reread, retry" loop.

Recommended usage:

• For small exact edits, read the smallest target range first, then use oldText / newText, expected_occurrences: 1, and line bounds when useful.

• For multiple independent edits in one file, use the edits array. All edits are matched against the original file content and applied bottom-up.

• For drifting middle text, use beforeText and afterText anchors.

• anchor_mode: "exact" is the default.

• anchor_mode: "flexible" means line-level trim matching only. It is not general fuzzy matching.

• Empty oldText returns EMPTY_MATCH_TEXT.

• Empty beforeText or afterText returns EMPTY_ANCHOR_TEXT.

• Match failures include structured diagnostics such as candidate counts/lines/ranges where useful.

Documentation

• Deployment guide

• Codex usage guide

• Tool reference

• Security notes

• Optimization notes

Upstream

This project is a modified K edition of the official MCP filesystem server:

• @modelcontextprotocol/server-filesystem

• https://github.com/modelcontextprotocol/servers

It is not affiliated with or endorsed by the upstream project.

License

MIT. See LICENSE and NOTICE.md.