FileMCP

FileMCP is a small Model Context Protocol (MCP) file server for AI Agents.

The server exposes simple file operations under an AgentFiles folder.

What It Does

FileMCP exposes these MCP tools:

• createFileTool: creates a new file under AgentFiles and refuses to silently overwrite an existing file.

• overwriteFileTool: writes or replaces a file under AgentFiles.

• createDirectoryTool: creates a directory under AgentFiles.

• readFileTool: reads a UTF-8 text file from AgentFiles.

• listDirectoryTool: lists files and folders under AgentFiles.

All five tools validate sandbox paths before accessing the filesystem. They reject absolute paths, .. components, Windows device names and alternate data streams, symbolic links, junctions, and hard-linked files. File creation uses an exclusive write so concurrent requests cannot silently replace an existing file. Failed operations return MCP's isError: true flag.

Related MCP server: files-mcp-ts

Requirements

• Node.js 20+

• npm

Install FileMCP

Once published to npm, install it from your agent project's root directory:

npm install @chey.dev/filemcp

Use With An Agent

Launch the installed executable as a stdio MCP server from your agent project:

npx --no-install filemcp

npx runs a package's executable. --no-install prevents it from installing a missing package, so install FileMCP with the command above first. The npm package is named @chey.dev/filemcp; its executable is named filemcp.

Configure your agent's MCP client to launch that command with its working directory set to the project whose AgentFiles sandbox you intend to use. No compilation is needed.

Connect From A Node.js App

Use the connection helper instead of repeating MCP client and stdio setup:

import { connectFileMcp } from "@chey.dev/filemcp/client";

const mcp = await connectFileMcp({ cwd: process.cwd() });
try {
	const { tools } = await mcp.listTools();
	console.log(tools.map((tool) => tool.name));
} finally {
	await mcp.close();
}

The helper starts FileMCP and returns a connected MCP SDK client. No separate server command or MCP client installation is needed. Importing the helper alone does not start the server.

cwd must name an existing directory; it defaults to the current working directory. Relative paths resolve from that directory. Files belong to AgentFiles beneath the selected directory, not beneath FileMCP's installation.

Use the returned client's listTools() and callTool() methods in your existing agent tool-calling logic. The helper does not call an AI model or translate AI requests. Always await mcp.close() when finished to stop the child server. If connecting fails, the helper attempts transport cleanup and rejects with the original error.

File Operations

File operations are relative to an AgentFiles folder in the server's startup working directory. This location is captured once and does not change if the process later changes its working directory. Asking the agent to read file.txt actually reads AgentFiles/file.txt. Same with writes.

The server creates AgentFiles automatically. Use . to list its root. Create nested directories before writing files into them. Overwrites are allowed only through overwriteFileTool; requesting a new file never overwrites existing data.

Security Boundary

These checks constrain paths supplied to this server's tools; they are not an operating-system sandbox. A hostile local process that can modify sandbox directories concurrently can race filesystem checks. Keep the sandbox and its parent directory under trusted control. For isolation from other local processes, run under a restricted OS account or in a container with only the intended sandbox mounted writable. Other filesystem or shell tools available to your agent are not restricted by this server.

Project Files

• server.js: creates the MCP server, registers tools, and starts stdio transport.

• client.js: connects Node.js applications to the server over stdio.

• tools.js: implements sandboxed filesystem tools.

• toolSchemas.js: defines tool descriptions and Zod schemas.