MCP Scoped Repo Server

An MCP (Model Context Protocol) server that provides Claude with scoped file access to a specific folder in a git repository.

Features

• Scoped Access: All file operations are restricted to a configured base directory
• Path Traversal Protection: Prevents ../ attacks and other escape attempts
• Create Files: Create new files or overwrite existing ones (with automatic parent directory creation)
• Read Files: Read file contents
• List Directories: Browse directory contents
• No Delete: Delete operations are intentionally not supported
• File Info: Get metadata about files and directories
• Git Operations: Stage, commit, pull, and push changes to remote repositories

Installation

npm install
npm run build

Configuration

Set the environment variable MCP_SCOPED_REPO_PATH to the absolute or relative path of the directory you want to scope access to.

Optionally set MCP_SCOPED_REPO_ROOT to the git repository root (defaults to MCP_SCOPED_REPO_PATH if not set). This is useful when you want file operations scoped to a subdirectory but git operations to work on the whole repo.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "scoped-repo": {
      "command": "node",
      "args": ["/path/to/mcp-scoped-repo/dist/index.js"],
      "env": {
        "MCP_SCOPED_REPO_PATH": "/path/to/your/repo/specific-folder"
      }
    }
  }
}

Claude Code Configuration

Add to your .mcp.json in your project root or home directory:

{
  "mcpServers": {
    "scoped-repo": {
      "command": "node",
      "args": ["/path/to/mcp-scoped-repo/dist/index.js"],
      "env": {
        "MCP_SCOPED_REPO_PATH": "./my-repo/allowed-folder"
      }
    }
  }
}

Available Tools

create_file

Create a new file or overwrite an existing file.

Parameters:

• path (string, required): Relative path within the scoped directory
• content (string, required): Content to write to the file

Example:

{
  "path": "subfolder/example.txt",
  "content": "Hello, world!"
}

read_file

Read the contents of a file.

Parameters:

• path (string, required): Relative path to the file

list_directory

List contents of a directory.

Parameters:

• path (string, required): Relative path to the directory (use . or empty string for root)

file_exists

Check if a file or directory exists.

Parameters:

• path (string, required): Relative path to check

Returns: "true" or "false"

get_file_info

Get metadata about a file or directory.

Parameters:

• path (string, required): Relative path to the file or directory

Returns: JSON with type, size, created, modified, and accessed timestamps

git_status

Show the working tree status in porcelain format.

Parameters: None

git_add

Stage a file for commit.

Parameters:

• path (string, required): Path to stage (use . to stage all changes)

git_commit

Commit staged changes.

Parameters:

• message (string, required): Commit message

git_pull

Pull changes from remote repository.

Parameters:

• remote (string, optional): Remote name (default: origin)
• branch (string, optional): Branch name (default: current branch)

git_push

Push commits to remote repository.

Parameters:

• remote (string, optional): Remote name (default: origin)
• branch (string, optional): Branch name (default: current branch)

Security

This server implements several security measures:

1. Base Path Restriction: All paths are resolved relative to the configured base path
2. Path Traversal Prevention: Attempts to escape the base directory (e.g., ../../../etc/passwd) are blocked
3. No Delete Operations: Intentionally omitted to prevent accidental data loss
4. No Access Above Base: Cannot read or list directories above the configured base path

Example Use Cases

• Allow Claude to manage content in a specific docs/ folder
• Give Claude access to a generated/ output directory
• Scope Claude's access to a specific module or component folder in your codebase

Development

# Watch mode for development
npm run dev

# Build
npm run build

# Run directly
MCP_SCOPED_REPO_PATH=/tmp/test-folder npm start