filesystem

This MCP server exposes filesystem-related tools to enable AI agents to read, write, update, and manage files and directories on the host machine. It supports two transports: STDIO for direct in-process communication and HTTP for network-based interactions secured with JWT when enabled. Tools include reading file contents, listing directories, creating, updating, moving, copying, and deleting files and directories, as well as targeted updates within files. The server sanitizes paths to prevent directory traversal and uses Zod for input validation to ensure safe, well-formed requests. To start, run the server (via Node) and choose your transport: STDIO will communicate over standard streams, while HTTP will expose REST endpoints with optional JWT authentication. You can adjust transport behavior and security through environment variables such as MCP_TRANSPORT_TYPE, MCP_HTTP_PORT, MCP_HTTP_HOST, MCP_ALLOWED_ORIGINS, and MCP_AUTH_SECRET_KEY. If you enable HTTP, ensure a strong JWT secret key and proper CORS origins are configured. The FS_BASE_DIRECTORY option lets you constrain all operations to a specific directory tree for additional security.

Prerequisites:

• Node.js installed (recommended LTS)
• npm or pnpm

Installation steps:

1. Clone the repository and install dependencies

git clone https://github.com/cyanheads/filesystem-mcp-server.git
cd filesystem-mcp-server
npm install

2. Build the TypeScript project to generate the runnable dist/index.js

npm run build

3. Run the server (example with STDIO transport, default settings)

# via Node (STDIO by default)
node dist/index.js

4. Optional: run via HTTP transport (ensure a secret key is set)

export MCP_TRANSPORT_TYPE=http
export MCP_HTTP_PORT=3010
export MCP_HTTP_HOST=127.0.0.1
export MCP_AUTH_SECRET_KEY=your-secure-32-plus-char-key-goes-here
node dist/index.js

5. If you prefer Docker, you would build/run with a suitable image (not shown in this repo’s current setup) or adapt the script to a container workflow.

Tips and considerations:

• For HTTP transport, always provide a strong MCP_AUTH_SECRET_KEY. ROTATE keys and keep them secret.
• Use FS_BASE_DIRECTORY to bound all file system operations to a safe sandbox. This is crucial for production deployments.
• If using HTTP, configure MCP_ALLOWED_ORIGINS to restrict who can access the MCP endpoints.
• The server uses Zod for input validation and path sanitization to minimize risks from malformed requests or path traversal attempts.
• Review LOGS_DIR and MCP_LOG_LEVEL to optimize observability in production.
• When deploying, consider enabling Server-Sent Events (SSE) for streaming updates if your client supports it.
• If you update environment variables, restart the server to apply changes.