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.

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Claude[Claude AI Assistant] <-->|JSON Protocol| MCP[FastFS-MCP Server]
    MCP <-->|File Operations| FS[Local Filesystem]
    MCP <-->|Git Operations| Git[Git Repositories]
    MCP <-->|Interactive Prompts| User[Human User]
    
    subgraph "FastFS-MCP Capabilities"
        FS
        Git
        User
    end

✨ 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

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Server[server.py] --> FastMCP[FastMCP Class]
    Server --> FileOps[Filesystem Operations]
    Server --> GitTools[git_tools.py]
    Server --> PromptHelpers[prompt_helpers.py]
    
    FileOps --> Basic[Basic Commands]
    FileOps --> Advanced[Advanced Operations]
    FileOps --> Text[Text Processing]
    FileOps --> Archive[Archive & Compression]
    
    GitTools --> BasicGit[Basic Git]
    GitTools --> AdvancedGit[Advanced Git]
    GitTools --> GitAnalysis[Repository Analysis]
    GitTools --> GitAuth[GitHub Authentication]
    
    PromptHelpers --> Templates[Prompt Templates]
    PromptHelpers --> Interactive[Interactive Tools]
    
    GitAuth --> PAT[Personal Access Token]
    GitAuth --> GitHubApp[GitHub App]
    GitHubApp --> DirectKey[Direct Key]
    GitHubApp --> KeyFromFile[Key from File]

💻 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:

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    MCP[FastFS-MCP] --> FS[Filesystem Operations]
    MCP --> Git[Git Operations]
    MCP --> Prompts[Interactive Prompts]
    MCP --> Processing[Text & File Processing]
    MCP --> Archive[Archive & Compression]
    
    FS --> Basic[Basic Operations]
    FS --> Advanced[Advanced Operations]
    
    Git --> BasicGit[Basic Commands]
    Git --> AdvancedGit[Advanced Analysis]
    Git --> GitHubAuth[GitHub Authentication]
    
    GitHubAuth --> PAT[Personal Access Token]
    GitHubAuth --> GitHubApp[GitHub App]
    
    Prompts --> Templates[Prompt Templates]
    Prompts --> Interactive[Interactive Tools]
    
    Processing --> Text[Text Manipulation]
    Processing --> Filters[Filters & Transformations]
    
    Archive --> Tar[Tar Operations]
    Archive --> Zip[Zip Operations]
    Archive --> Compress[Compression Tools]

🗂️ Filesystem Operations

Basic Operations

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph LR
    ls[ls] --> list[List files and directories]
    cd[cd] --> change[Change current directory]
    pwd[pwd] --> print[Print working directory]
    read[read] --> display[Display file contents]
    write[write] --> create[Create or modify files]
    grep[grep] --> search[Search file content]
    which[which] --> locate[Locate executables]

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

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Git[Git Operations] --> Repo[Repository Management]
    Git --> Changes[Change Management]
    Git --> Branch[Branch Operations]
    Git --> Remote[Remote Operations]
    Git --> Analysis[Repository Analysis]
    Git --> Auth[GitHub Authentication]
    
    Repo --> init[Initialize Repository]
    Repo --> clone[Clone Repository]
    Repo --> status[Check Status]
    
    Changes --> add[Stage Changes]
    Changes --> commit[Commit Changes]
    Changes --> diff[View Differences]
    
    Branch --> checkout[Switch Branches]
    Branch --> branch[Manage Branches]
    Branch --> merge[Merge Branches]
    
    Remote --> push[Push Changes]
    Remote --> pull[Pull Changes]
    Remote --> fetch[Fetch Updates]
    
    Analysis --> context[Get Repository Context]
    Analysis --> validate[Validate Repository]
    Analysis --> suggest[Suggest Commit Messages]
    Analysis --> audit[Audit Repository History]
    
    Auth --> PAT[Personal Access Token]
    Auth --> GitHubApp[GitHub App]

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

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
graph TD
    Prompts[Interactive Prompts] --> Templates[Prompt Templates]
    Prompts --> Operations[Prompt Operations]
    
    Templates --> FilePrompts[File Prompts]
    Templates --> ContentPrompts[Content Prompts]
    Templates --> ProjectPrompts[Project Prompts]
    Templates --> CustomPrompts[Custom Prompts]
    
    Operations --> prompt[Send Prompt]
    Operations --> interactive_write[Interactive Write]
    Operations --> confirm_overwrite[Confirm Overwrite]
    Operations --> select_file[Select File]
    Operations --> get_file_content[Get File Content]
    Operations --> init_project[Initialize Project]
    
    FilePrompts --> confirm_file_overwrite[Confirm File Overwrite]
    FilePrompts --> confirm_directory_delete[Confirm Directory Delete]
    FilePrompts --> file_not_found_options[File Not Found Options]
    
    ContentPrompts --> enter_file_content[Enter File Content]
    ContentPrompts --> enter_search_pattern[Enter Search Pattern]
    
    ProjectPrompts --> project_initialization[Project Initialization]
    ProjectPrompts --> coding_task[Coding Task]
    
    CustomPrompts --> custom[Custom Message]

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

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
sequenceDiagram
    participant Claude
    participant FastFS
    participant GitHub
    
    Claude->>FastFS: git_clone(private_repo_url)
    FastFS->>GitHub: Authentication with PAT
    GitHub-->>FastFS: Authentication successful
    FastFS->>GitHub: Clone repository
    GitHub-->>FastFS: Repository content
    FastFS-->>Claude: Clone successful

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

%%{ init: { "theme": "dark", "look": "handDrawn", "themeVariables": { "handDrawn": true } } }%%
sequenceDiagram
    participant Claude
    participant FastFS
    participant GitHub
    
    Claude->>FastFS: git_clone(private_repo_url)
    FastFS->>FastFS: Generate JWT using private key
    FastFS->>GitHub: Request installation token with JWT
    GitHub-->>FastFS: Installation token
    FastFS->>GitHub: Clone repository with installation token
    GitHub-->>FastFS: Repository content
    FastFS-->>Claude: Clone successful

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:

1. 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

2. 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:

1. Only run FastFS-MCP with appropriate file system permissions
2. Mount only the directories you need to expose to Claude
3. Use separate GitHub PATs with limited scope for authentication, or prefer GitHub Apps for better security
4. Regularly review the logs and commands executed by the server
5. For GitHub Apps, store the private key securely and use installation-specific tokens
6. 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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.