fastmcp-file

FastMCP File Server is a Python-based MCP server that provides secure, rule-based file operations to AI assistants. It supports multiple connection modes, including stdio, HTTP, and public access via ngrok, and enforces a configurable access model with read, write, and admin tokens. The server restricts all operations to a safe, configured directory and offers features such as reading, creating, deleting, moving, and archiving files, along with text manipulation, hash verification, and format conversions. To integrate with Claude Desktop or similar tools, you can expose the server locally via stdio, then connect through HTTP or via an HTTP proxy setup using mcp-remote, and optionally expose it publicly with ngrok for remote access.

The available capabilities include: creating, reading, writing, deleting, copying, moving, and renaming files and directories; text operations like line-based reads and search/replace; file analysis such as size, timestamps, and hashes; batch operations; ZIP archive creation/extraction; basic format conversions (e.g., text to PDF, CSV↔JSON); and safe directory scoping via the MCP_ALLOWED_PATH environment setting. Authentication is token-based, with separate tokens for read, write, and admin permissions, and HTTP access is only enabled when tokens are configured. When tokens are not set, HTTP endpoints may be open in secure environments, but it is strongly recommended to use tokens for any exposure outside local stdio usage.

To use the server in a typical workflow, deploy the server in your preferred mode (stdio for local automation, HTTP for web-app integrations, or via ngrok for public access), then configure your MCP client (or Claude Desktop) to point at the local or remote /mcp endpoint, supplying the appropriate Authorization header if tokens are configured.

Prerequisites

• Python 3.8+ (recommended)
• Access to install Python packages (pip)
• Optional: uv command-line tool (see installation steps)

Installation steps

1. Ensure Python is installed and available in your PATH
   • Check: python3 --version or python --version
2. Install the uv (Uvicorn/UV) tool if not already present. Example (recommended):
   • python -m pip install uvx
   • Or follow the project’s preferred installation method for uv (as shown in the README): uv tool install fastmcp-file-server
3. Install the FastMCP File Server package
   • Using uvx to install the MCP server package (as required by the repository): uvx tool install fastmcp-file-server
4. Verify installation
   • Ensure the fastmcp-file-server executable is available in your PATH (or use the http variant if applicable): fastmcp-file-server fastmcp-file-server-http
5. Prepare configuration (optional but recommended)
   • Create a .env file or export environment variables as described in the README (MCP_ALLOWED_PATH, MCP_HTTP_PORT, MCP_ADMIN_KEY, etc.).

Tips and common considerations:

• Always set MCP_ALLOWED_PATH to limit file operations to a safe directory.
• Use multi-tier tokens (MCP_READ_KEY, MCP_WRITE_KEY, MCP_ADMIN_KEY) to control access levels; when any token is set, HTTP requests require Authorization headers.
• For ngrok/public exposure, use strong tokens and revoke access promptly after use.
• If starting the HTTP server without any tokens, expect a security warning and consider using --ignore-keys only in trusted environments.
• Regularly rotate tokens and monitor logs for unauthorized access attempts.
• When integrating with Claude or similar tools, you can use mcp-remote to proxy HTTP requests if needed.