FastFS-MCP

A high-speed MCP (Model Context Protocol) server for filesystem operations, Git integration, and interactive prompting capabilities, designed to work seamlessly with Claude and AI-native tooling.

🚀 Overview

FastFS-MCP enables AI assistants like Claude to interact with your local filesystem, manage Git repositories, and provide interactive experiences through a standardized JSON-based protocol. Whether you're building AI-assisted development workflows, creating content with Claude, or automating file management tasks, FastFS-MCP provides the bridge between your AI assistant and your local environment.

✨ Key Features

Ultra-fast filesystem operations: Access, modify, and manage files with minimal latency
Complete Git integration: Perform all standard Git operations and advanced repository analysis
Interactive prompting: Enable Claude to engage users through structured prompts and forms
GitHub authentication: Securely authenticate with GitHub using personal access tokens or GitHub Apps
JSON protocol: Communicate with Claude Desktop, VSCode, and other AI-native tools using a standard interface

🛠️ Core Components Architecture

💻 Installation & Quick Start

Docker Quick Start

# Build the Docker image
docker build -t fastfs-mcp .

# Run with your local filesystem mounted
docker run -i --rm \
  -v C:\\Users\\username:/mnt/workspace:rw \
  fastfs-mcp

On Unix/macOS: replace with -v $HOME:/mnt/workspace

With GitHub Authentication

Using Personal Access Token

docker run -i --rm \
  -v C:\\Users\\username:/mnt/workspace:rw \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here \
  fastfs-mcp

Using GitHub App (Option 1: Private Key as Environment Variable)

docker run -i --rm \
  -v C:\\Users\\username:/mnt/workspace:rw \
  -e GITHUB_APP_ID=your_app_id \
  -e GITHUB_APP_PRIVATE_KEY="$(cat path/to/private-key.pem)" \
  -e GITHUB_APP_INSTALLATION_ID=your_installation_id \
  fastfs-mcp

Using GitHub App (Option 2: Private Key from File in Workspace)

# First, copy your private key to the workspace
cp path/to/private-key.pem C:\\Users\\username\\github-app-key.pem

# Then run with the path to the private key
docker run -i --rm \
  -v C:\\Users\\username:/mnt/workspace:rw \
  -e GITHUB_APP_ID=your_app_id \
  -e GITHUB_APP_PRIVATE_KEY_PATH=/mnt/workspace/github-app-key.pem \
  -e GITHUB_APP_INSTALLATION_ID=your_installation_id \
  fastfs-mcp

🤖 Claude Desktop Configuration

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "C:\\Users\\username:/mnt/workspace:rw",
        "fastfs-mcp"
      ]
    }
  }
}

With GitHub Authentication

Using Personal Access Token

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", 
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "-v", "C:\\Users\\username:/mnt/workspace:rw",
        "fastfs-mcp"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Using GitHub App with Private Key as Environment Variable

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", 
        "-e", "GITHUB_APP_ID",
        "-e", "GITHUB_APP_PRIVATE_KEY",
        "-e", "GITHUB_APP_INSTALLATION_ID",
        "-v", "C:\\Users\\username:/mnt/workspace:rw",
        "fastfs-mcp"
      ],
      "env": {
        "GITHUB_APP_ID": "your_app_id",
        "GITHUB_APP_PRIVATE_KEY": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
        "GITHUB_APP_INSTALLATION_ID": "your_installation_id"
      }
    }
  }
}

Using GitHub App with Private Key from File

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", 
        "-e", "GITHUB_APP_ID",
        "-e", "GITHUB_APP_PRIVATE_KEY_PATH",
        "-e", "GITHUB_APP_INSTALLATION_ID",
        "-v", "C:\\Users\\username:/mnt/workspace:rw",
        "fastfs-mcp"
      ],
      "env": {
        "GITHUB_APP_ID": "your_app_id",
        "GITHUB_APP_PRIVATE_KEY_PATH": "/mnt/workspace/github-app-key.pem",
        "GITHUB_APP_INSTALLATION_ID": "your_installation_id"
      }
    }
  }
}

📋 Tool Categories

FastFS-MCP provides a comprehensive set of tools organized into logical categories:

🗂️ Filesystem Operations

Basic Operations

Method	Description
`ls`	List files in a directory
`cd`	Change the current working directory
`pwd`	Print the current working directory
`read`	Read file contents
`write`	Create or overwrite file content
`grep`	Fast file searching via ripgrep
`which`	Locate executables in PATH

Advanced Operations

Method	Description
`tree`	Display directory structure
`find`	Find files by pattern
`cp`	Copy files or directories
`mv`	Move or rename files
`rm`	Remove files or directories
`mkdir`	Create directories
`stat`	Display file metadata
`chmod`	Change file permissions
`du`	Show disk usage
`df`	Show disk space
`touch`	Create a new empty file or update timestamp

Text & File Processing

Method	Description
`sed`	Stream editor for text transformation
`gawk`	Text processing with AWK
`head`	Show first lines of a file
`tail`	Show last lines of a file
`wc`	Count lines, words, and bytes
`cut`	Select columns from file
`sort`	Sort lines of text files
`uniq`	Report or filter repeated lines
`nl`	Number lines in a file
`split`	Split a file into smaller parts
`readlink`	Print the resolved path of a symbolic link
`realpath`	Print the resolved absolute path

Archive & Compression

Method	Description
`tar`	Create/extract tar archives
`gzip`	Compress/decompress files
`zip`	Create/extract zip archives

🌿 Git Operations

Basic Git Operations

Method	Description
`clone`	Clone a Git repository
`init`	Initialize a new Git repository
`add`	Add file(s) to staging area
`commit`	Commit changes to repository
`status`	Show working tree status
`push`	Push changes to remote repository
`pull`	Pull changes from remote repository
`log`	Show commit logs
`checkout`	Switch branches or restore files
`branch`	List, create, or delete branches
`merge`	Join development histories together
`show`	Show Git objects
`diff`	Show changes between commits/working tree
`remote`	Manage remote repositories
`stash`	Stash changes in working directory
`tag`	Manage Git tags
`config`	Get or set repository or global options
`fetch`	Download objects and refs from another repository
`blame`	Show what revision and author last modified each line of a file
`git_grep`	Print lines matching a pattern in tracked files
`head`	Show the current HEAD commit information

Advanced Git Analysis

Method	Description
`context`	Get comprehensive repo context
`repo_info`	Get detailed repository information
`validate`	Check repository for common issues
`summarize_log`	Generate commit log statistics
`suggest_commit`	Auto-suggest commit messages
`audit_history`	Audit repository for security issues

🤝 Interactive Prompts

Prompt Templates

Template	Description
`confirm_file_overwrite`	Ask user to confirm before overwriting an existing file
`confirm_directory_delete`	Warn user before deleting a directory
`file_not_found_options`	Provide options when a file is not found
`enter_file_content`	Get content for a file from the user
`enter_search_pattern`	Ask user for a search pattern
`project_initialization`	Collect information to initialize a new project
`coding_task`	Define parameters of a coding task
`select_file_from_list`	Let user select a file from a list
`custom`	Create a completely custom prompt message

Interactive Functions

Function	Description
`prompt`	Send an interactive prompt to the user
`get_prompt_types`	List available prompt templates
`interactive_write`	Write file with user-provided content
`confirm_overwrite`	Ask before overwriting files
`select_file`	Let user choose from file list
`get_file_content`	Get content for file from user
`init_project`	Initialize project with guided setup

📝 Protocol Usage

FastFS-MCP uses a simple JSON-based protocol to communicate with Claude and other AI tools.

Request Format

{
  "method": "METHOD_NAME",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

Response Format

{
  "result": RESPONSE_DATA
}

Examples

Basic File Operation

// Request
{
  "method": "ls",
  "params": { "path": "." }
}

// Response
{
  "result": ["main.tf", "README.md"]
}

Git Repository Context

// Request
{
  "method": "context",
  "params": {}
}

// Response
{
  "result": {
    "current_branch": "main",
    "repository_root": "/mnt/workspace/my-project",
    "is_clean": false,
    "head_commit": "a1b2c3d4e5f6...",
    "remotes": {
      "origin": "https://github.com/user/repo.git"
    },
    "recent_commits": [
      "a1b2c3d4 Update README.md",
      "b2c3d4e5 Fix bug in main function",
      "c3d4e5f6 Add new feature"
    ]
  }
}

Interactive Prompt Flow

// Request
{
  "method": "prompt",
  "params": { 
    "prompt_type": "custom", 
    "message": "What would you like to name your file?" 
  }
}

// Response to stdout (visible to user)
{
  "type": "user_prompt",
  "prompt": "What would you like to name your file?"
}

// User response (from stdin)
{
  "type": "user_response",
  "response": "myfile.txt"
}

// Final result to Claude
{
  "result": {
    "response": "myfile.txt",
    "timestamp": 1622548123.45
  }
}

🔧 GitHub Authentication

FastFS-MCP supports two methods of GitHub authentication to enable secure Git operations with GitHub repositories:

Personal Access Token (PAT) Authentication

When a GitHub PAT is provided via the GITHUB_PERSONAL_ACCESS_TOKEN environment variable, Git operations that interact with GitHub (clone, push, pull, fetch) will automatically use the token for authentication, enabling:

Access to private repositories
Operations that require authentication (push, create repo, etc.)
Avoiding rate limits on API calls

GitHub App Authentication

GitHub App authentication provides more granular permissions and better security compared to Personal Access Tokens:

Fine-grained permissions: GitHub Apps can be configured with specific permissions
Repository-specific access: GitHub Apps can be installed on specific repositories
Organization-level control: Organization admins can control which apps are installed
Automatic token refresh: Installation tokens expire after 1 hour and are automatically refreshed

To use GitHub App authentication, provide the following environment variables:

GITHUB_APP_ID: Your GitHub App's ID

And one of these options for the private key:

GITHUB_APP_PRIVATE_KEY: The private key content for your GitHub App (PEM format) as an environment variable
GITHUB_APP_PRIVATE_KEY_PATH: Path to a file containing the private key (PEM format)

Optionally:

GITHUB_APP_INSTALLATION_ID: The specific installation ID to use (if not provided, FastFS-MCP will attempt to use the first installation)

Security Considerations for Private Keys

When using GitHub App authentication, consider these security practices for managing private keys:

File-based private key (recommended):
- Store your private key in your workspace and use GITHUB_APP_PRIVATE_KEY_PATH
- Ensure proper file permissions (chmod 600) on the private key file
- This approach avoids having the key in process environment variables or shell history
Environment variable private key:
- Use this for development or when you can't mount a file
- Be aware that environment variables can be visible in process lists on some systems

🐳 Docker Environment

FastFS-MCP runs in a Docker container for portability and isolation, with the following tools installed:

ripgrep for high-performance file searching
jq for JSON parsing and manipulation
sed and gawk for text processing
tree for directory visualization
fd-find for alternative file finding
coreutils for standard Unix tools
zip/unzip, gzip, and xz-utils for compression
git for repository operations

🚀 Use Cases

AI-assisted development: Let Claude help you code, manage files, and use Git all within the same conversation
Content creation workflows: Enable Claude to read, write, and organize files for writing projects
Repository management: Get insights into Git repositories and automate common Git operations
Interactive project setup: Guide users through structured project initialization with interactive prompts
System administration: Perform file system operations and maintenance tasks with AI assistance

🔒 Security Considerations

FastFS-MCP provides direct access to your filesystem and Git repositories. Consider the following security practices:

Only run FastFS-MCP with appropriate file system permissions
Mount only the directories you need to expose to Claude
Use separate GitHub PATs with limited scope for authentication, or prefer GitHub Apps for better security
Regularly review the logs and commands executed by the server
For GitHub Apps, store the private key securely and use installation-specific tokens
When using GitHub App authentication, prefer file-based private keys over environment variables when possible

📄 License

FastFS-MCP is released under the MIT License. See the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📚 Further Documentation

Prompt Guide - Detailed documentation on interactive prompts
Claude Prompt Examples - Examples of how Claude can use FastFS-MCP
Claude Prompt Guide - Guide for Claude on working with FastFS-MCP

Built for AI-enhanced CLI and developer workflows with speed, structure, and simplicity.

This server cannot be installed

security - not tested

license - not found

quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A high-speed MCP server that enables AI assistants like Claude to interact with local filesystems, manage Git repositories, and provide interactive experiences through a standardized JSON-based protocol.

Related MCP Servers

Filesystem MCP Server
ai-yliu
-
security
F
license
-
quality
An MCP server that allows Claude AI to perform filesystem operations including reading, writing, listing, moving files, and searching directories within specified allowed paths.
Last updated -
5
1
JavaScript
MCP Claude Code
SDGLBL
-
security
A
license
-
quality
An MCP server that implements Claude Code-like functionality, allowing the AI to analyze codebases, modify files, execute commands, and manage projects through direct file system interactions.
Last updated -
179
Python
MIT License
Terminal MCP Server
theailanguage
-
security
F
license
-
quality
An MCP server that allows AI assistants like Claude to execute terminal commands on the user's computer and return the output, functioning like a terminal through AI.
Last updated -
7
Python
file-system-mcp-server
calebmwelsh
-
security
A
license
-
quality
A comprehensive MCP (Model Context Protocol) server for file system operations, providing Claude and other AI assistants with access to local files and directories.
Last updated -
Python
MIT License

View all related MCP servers

FastFS-MCP

🚀 Overview

✨ Key Features

🛠️ Core Components Architecture

💻 Installation & Quick Start

Docker Quick Start

With GitHub Authentication

Using Personal Access Token

Using GitHub App (Option 1: Private Key as Environment Variable)

Using GitHub App (Option 2: Private Key from File in Workspace)

🤖 Claude Desktop Configuration

With GitHub Authentication

Using Personal Access Token

Using GitHub App with Private Key as Environment Variable

Using GitHub App with Private Key from File

📋 Tool Categories

🗂️ Filesystem Operations

Basic Operations

Advanced Operations

Text & File Processing

Archive & Compression

🌿 Git Operations

Basic Git Operations

Advanced Git Analysis

🤝 Interactive Prompts

Prompt Templates

Interactive Functions

📝 Protocol Usage

Request Format

Response Format

Examples

Basic File Operation

Git Repository Context

Interactive Prompt Flow

🔧 GitHub Authentication

Personal Access Token (PAT) Authentication

GitHub App Authentication

Security Considerations for Private Keys

🐳 Docker Environment

🚀 Use Cases

🔒 Security Considerations

📄 License

🤝 Contributing

📚 Further Documentation

Related MCP Servers

Filesystem MCP Server

MCP Claude Code

Terminal MCP Server

file-system-mcp-server

New MCP Servers

MCP directory API