GitHub Fetcher MCP

MCP (Model Context Protocol) server for fetching GitHub repository files and directory trees.

Features

• fetch-file: Fetch raw file content from GitHub repositories
• fetch-subdir-tree: Fetch directory tree structure in unix tree format
• fetch-sub-tree ⭐ NEW: Enhanced directory tree with file sizes, depth limits, statistics, and filtering
• Flexible configuration via CLI arguments or per-request parameters
• Built with TypeScript for type safety
• Comprehensive test coverage (79 tests)

Installation

NPM

npm install -g github-fetcher-mcp

Smithery

To install GitHub Fetcher MCP Server for any client automatically via Smithery:

npx -y @smithery/cli@latest install github-fetcher-mcp --client <CLIENT_NAME>

Available clients: cursor, claude, vscode, windsurf, cline, zed, etc.

Example for Cursor:

npx -y @smithery/cli@latest install github-fetcher-mcp --client cursor

This will automatically configure the MCP server in your chosen client.

MCP Client Integration

GitHub Fetcher MCP can be integrated with various AI coding assistants and IDEs that support the Model Context Protocol (MCP).

Requirements

• Node.js >= v18.0.0
• An MCP-compatible client (Cursor, Claude Code, VS Code, Windsurf, etc.)

{
  "mcpServers": {
    "github-fetcher": {
      "command": "npx",
      "args": ["-y", "github-fetcher-mcp", "--repoIdentifier", "facebook/react/main"]
    }
  }
}

{
  "mcpServers": {
    "github-fetcher": {
      "command": "npx",
      "args": ["-y", "github-fetcher-mcp"]
    }
  }
}

claude mcp add github-fetcher -- npx -y github-fetcher-mcp --repoIdentifier facebook/react/main

claude mcp add github-fetcher -- npx -y github-fetcher-mcp

"mcp": {
  "servers": {
    "github-fetcher": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github-fetcher-mcp", "--repoIdentifier", "facebook/react/main"]
    }
  }
}

{
  "mcpServers": {
    "github-fetcher": {
      "command": "npx",
      "args": ["-y", "github-fetcher-mcp", "--repoIdentifier", "facebook/react/main"]
    }
  }
}

{
  "mcpServers": {
    "github-fetcher": {
      "command": "npx",
      "args": ["-y", "github-fetcher-mcp", "--repoIdentifier", "facebook/react/main"]
    }
  }
}

{
  "mcpServers": {
    "github-fetcher": {
      "command": "npx",
      "args": ["-y", "github-fetcher-mcp", "--repoIdentifier", "facebook/react/main"]
    }
  }
}

{
  "context_servers": {
    "github-fetcher": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "github-fetcher-mcp", "--repoIdentifier", "facebook/react/main"]
    }
  }
}

{
  "mcpServers": {
    "github-fetcher": {
      "command": "npx",
      "args": ["-y", "github-fetcher-mcp", "--repoIdentifier", "facebook/react/main"]
    }
  }
}

{
  "mcpServers": {
    "github-fetcher": {
      "command": "bunx",
      "args": ["-y", "github-fetcher-mcp", "--repoIdentifier", "facebook/react/main"]
    }
  }
}

FROM node:18-alpine

WORKDIR /app

# Install the package globally
RUN npm install -g github-fetcher-mcp

# Expose the server port
EXPOSE 3000

# Default command to run the server
CMD ["github-fetcher-mcp"]

docker build -t github-fetcher-mcp .

{
  "mcpServers": {
    "github-fetcher": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-p", "3000:3000", "github-fetcher-mcp", "--repoIdentifier", "facebook/react/main"]
    }
  }
}

Usage

With Repository Identifier (CLI Argument)

When you provide a --repoIdentifier argument, all tools will use that repository by default:

github-fetcher-mcp --repoIdentifier facebook/react/main

Tools available:

• fetch-file: Requires only filePath
• fetch-subdir-tree: Requires only dirPath
• fetch-sub-tree: Requires only dirPath (+ optional: showSize, maxDepth, showStats, fileExtFilter)

Without Repository Identifier

When no repository identifier is provided, you can specify the repository for each request:

github-fetcher-mcp

Tools available:

• fetch-file: Requires ownerName, repoName, branchName (optional, default: 'main'), and filePath
• fetch-subdir-tree: Requires ownerName, repoName, branchName (optional, default: 'main'), and dirPath
• fetch-sub-tree: Requires ownerName, repoName, branchName (optional, default: 'main'), dirPath (+ optional: showSize, maxDepth, showStats, fileExtFilter)

Available Tools

GitHub Fetcher MCP provides the following tools that can be used by LLMs:

• fetch-file: Fetches the raw content of a file from a GitHub repository

  • Required parameters vary based on whether --repoIdentifier is provided
  • Returns the complete file content as text

• fetch-subdir-tree: Fetches directory tree structure in unix tree format

  • Required parameters vary based on whether --repoIdentifier is provided
  • Returns formatted directory tree showing files and subdirectories

• fetch-sub-tree ⭐ NEW: Enhanced version with advanced options

  • Required parameters vary based on whether --repoIdentifier is provided
  • Optional parameters:
    • showSize (boolean): Show file and directory sizes
    • maxDepth (number): Limit tree depth (e.g., 1 for immediate children only)
    • showStats (boolean): Show statistics summary (default: true)
    • fileExtFilter (string[]): Filter files by extensions (e.g., [".ts", ".js"])
  • Returns enhanced directory tree with optional file sizes and statistics

Usage Examples

Example 1: Fetch a specific file

In Cursor/Claude Code:

Fetch the package.json file from the facebook/react repository on the main branch

In any MCP client (with repoIdentifier configured):

Show me the contents of src/index.ts

Example 2: Browse directory structure

In Cursor/Claude Code:

Show me the directory structure of the src folder in microsoft/vscode on the main branch

In any MCP client (with repoIdentifier configured):

What files are in the components directory?

Example 3: Analyze code structure

In Cursor/Claude Code:

I want to understand the structure of the Next.js repository.
Show me the directory tree of the packages folder from vercel/next.js on the canary branch.
Then fetch the package.json file to see the dependencies.

Tool Reference

fetch-file

Fetches the raw content of a file from a GitHub repository.

With repoIdentifier:

{
  "filePath": "src/index.ts"
}

Without repoIdentifier:

{
  "ownerName": "facebook",
  "repoName": "react",
  "branchName": "main",
  "filePath": "src/index.ts"
}

fetch-subdir-tree

Fetches directory tree structure in unix tree format.

With repoIdentifier:

{
  "dirPath": "src"
}

Without repoIdentifier:

{
  "ownerName": "microsoft",
  "repoName": "vscode",
  "branchName": "main",
  "dirPath": "src"
}

fetch-sub-tree ⭐ NEW

Enhanced directory tree with file sizes, depth limits, and filtering options.

With repoIdentifier - Basic usage:

{
  "dirPath": "src"
}

With repoIdentifier - Show file sizes:

{
  "dirPath": "src",
  "showSize": true
}

With repoIdentifier - Limit depth:

{
  "dirPath": "src",
  "maxDepth": 2
}

With repoIdentifier - Filter by file extensions:

{
  "dirPath": "src",
  "fileExtFilter": [".ts", ".tsx"]
}

With repoIdentifier - All options:

{
  "dirPath": "src",
  "showSize": true,
  "maxDepth": 3,
  "showStats": true,
  "fileExtFilter": [".ts", ".js"]
}

Example Output (with showSize and showStats):

src/
├── components/ (2 files, 15.3KB)
│   ├── Button.tsx (8.2KB)
│   └── Input.tsx (7.1KB)
└── utils/ (3 files, 5.8KB)
    ├── helpers.ts (2.1KB)
    ├── format.ts (1.9KB)
    └── validate.ts (1.8KB)

📊 Summary: 2 directories, 5 files, 21.1KB total

Without repoIdentifier:

{
  "ownerName": "microsoft",
  "repoName": "vscode",
  "branchName": "main",
  "dirPath": "src",
  "showSize": true,
  "maxDepth": 2
}

Docker Usage

Build Docker Image

docker build -t github-fetcher-mcp .

Run with Docker

With repoIdentifier:

docker run -d -p 3000:3000 \
  --name github-fetcher \
  github-fetcher-mcp \
  node dist/server.js --repoIdentifier facebook/react/main

Without repoIdentifier:

docker run -d -p 3000:3000 \
  --name github-fetcher \
  github-fetcher-mcp

Docker Compose Example

Create a docker-compose.yml:

version: '3.8'

services:
  github-fetcher-mcp:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - NODE_ENV=production
    command: ["node", "dist/server.js", "--repoIdentifier", "facebook/react/main"]
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/mcp', (r) => {process.exit(r.statusCode === 200 ? 0 : 1)})"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

Run with Docker Compose:

docker-compose up -d

Use Docker Image in MCP Clients

Configure your MCP client to use the Docker container:

{
  "mcpServers": {
    "github-fetcher": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "github-fetcher-mcp",
        "node",
        "dist/server.js",
        "--repoIdentifier",
        "facebook/react/main"
      ]
    }
  }
}

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build
npm run build

# Type check
npm run typecheck

# Lint
npm run lint

Architecture

The project follows a modular architecture:

• config/: CLI argument parsing
• services/: GitHub API integration and tree formatting
• tools/: MCP tool implementations
• types/: TypeScript type definitions
• utils/: Utility functions

Testing

The project has comprehensive test coverage:

• Unit tests for all services, tools, and utilities
• Integration tests for tool creation
• 79 total tests, all passing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

License

MIT

Contributing

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

Author

choesumin