Github Explorer MCP

🚀 GitHub Explorer MCP Server

This MCP (Middleware Protocol) server provides information about GitHub repositories, including file contents, directory structures, and other metadata, for clients such as Claude Desktop and Cursor.

🚀 Quick Start

This MCP server offers a wide range of features to access and manage GitHub repository information. It can be easily installed and integrated with popular clients.

✨ Features

• Repository Summary: Get comprehensive information about a GitHub repository.
• Directory Structure: View the complete file structure of any repository in an ASCII tree format.
• File Content: Access the content of specific files.
• Metadata Enhancement: Retrieve information such as stars, forks, description, and last update time.
• Local Repository Cloning: Clone repositories locally for faster processing and more comprehensive data.
• Caching System: Efficiently cache repository data to reduce API calls.
• Progress Notification: Receive status updates for long - running operations.
• Format Options: Obtain data in text or structured JSON format.
• Autocomplete: Get suggestions for repository owners and names.
• Web Interface: Provide a basic status page and information when running in HTTP mode.

📦 Installation

Using NPM

# Install from npm
npm install @trishchuk/github-explorer-mcp -g

# Run the server (stdio mode for MCP clients)
github-explorer-mcp

# Or run in HTTP/SSE mode
github-explorer-mcp-sse

Using Docker

# Build the Docker image
docker build -t github-explorer-mcp .

# Run the container
docker run -p 3000:3000 github-explorer-mcp

💻 Usage Examples

Using with MCP Clients

Claude Desktop

Add the following to the Claude Desktop configuration:

{
  "mcpServers": {
    "github-explorer": {
      "command": "npx",
      "args": ["-y", "@trishchuk/github-explorer-mcp"]
    }
  }
}

Cursor

Add the following to the Cursor configuration:

{
  "mcpServers": {
    "github-explorer": {
      "command": "npx",
      "args": ["-y", "@trishchuk/github-explorer-mcp"]
    }
  }
}

📚 Documentation

API Reference

The MCP server provides the following tools:

github_repository_summary

Get a summary of a GitHub repository.

{
  owner: string;    // GitHub organization or user name
  repo: string;     // Repository name
  branch?: string;  // Optional branch name
  includeMetadata?: boolean; // Whether to include metadata such as stars, forks
}

github_directory_structure

Get the directory structure of a GitHub repository.

{
  owner: string;    // GitHub organization or user name
  repo: string;     // Repository name
  branch?: string;  // Optional branch name
}

github_file_content

Get the content of a file in a GitHub repository.

{
  owner: string;    // GitHub organization or user name
  repo: string;     // Repository name
  file_path: string; // File path
  branch?: string;  // Optional branch name
}

🔧 Technical Details

Development

Clone the Repository

Clone the project using the following command:

git clone https://github.com/yourusername/github-explorer-mcp.git
cd github-explorer-mcp

Install Dependencies

Install the project's required dependencies:

npm install

Run the Project

Run the project:

npm start

Troubleshooting

Node.js Version Issue

Make sure to use Node.js 18 or a higher version. If there are issues, check and upgrade Node.js.

Docker Deployment Issue

If you encounter problems during Docker deployment, confirm that the image is correctly built and the container configuration is correct.

🤝 Contribution

Welcome to submit Pull Requests to help improve this project!