GitHub MCP Server for Cursor

This project implements a Model Context Protocol (MCP) server that integrates with GitHub to provide comprehensive functionality for web-based projects in Cursor.

Features

• Repository information and structure
• File content access
• Branch management
• Issue tracking and management
• Project management
• Support for both stdio and SSE transport options

Prerequisites

• Node.js (v14 or later)
• npm (v6 or later)
• GitHub Personal Access Token with appropriate permissions:
  • repo (Full repository access)
  • project (Project access)
  • write:org (Organization access)

Installation

1. Clone the repository:

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

2. Install dependencies:

   npm install

3. Create a .env file in the root directory with your GitHub credentials:

   GITHUB_TOKEN=your_github_personal_access_token
   GITHUB_OWNER=default_repository_owner
   GITHUB_REPO=default_repository_name
   PORT=3000
   HOST=0.0.0.0
   NODE_ENV=development
   DEFAULT_TRANSPORT=stdio

Usage

Starting the server with stdio transport (local development)

npm run start:stdio

Starting the server with SSE transport (networked access)

npm run start:sse

Configuring Cursor to use the MCP server

Project-specific configuration

Create a .cursor/mcp.json file in your project root:

{
  "servers": [
    {
      "name": "github-mcp-server",
      "command": "npm",
      "args": ["run", "start:stdio"],
      "cwd": "/path/to/github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token",
        "GITHUB_OWNER": "your_github_username",
        "GITHUB_REPO": "your_repository_name"
      }
    }
  ]
}

Global configuration

Create a ~/.cursor/mcp.json file:

{
  "servers": [
    {
      "name": "github-mcp-server",
      "command": "npm",
      "args": ["run", "start:stdio"],
      "cwd": "/path/to/github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token",
        "GITHUB_OWNER": "your_github_username",
        "GITHUB_REPO": "your_repository_name"
      }
    }
  ]
}

Using SSE transport

For SSE transport, modify the configuration:

{
  "servers": [
    {
      "name": "github-mcp-server",
      "url": "http://localhost:3000/sse"
    }
  ]
}

Available Tools

The MCP server exposes the following tools to Cursor:

• github_repository_info: Get information about a GitHub repository
• github_directory_structure: Get the directory structure of a GitHub repository
• github_read_file: Read a file from a GitHub repository
• github_list_branches: List branches in a GitHub repository
• github_list_issues: List issues in a GitHub repository
• github_create_issue: Create a new issue in a GitHub repository
• github_list_projects: List GitHub projects
• github_create_project: Create a new GitHub project

For detailed information about each tool, see the API Reference.

Development

Building the project

npm run build

Running tests

npm test

Linting

npm run lint

Formatting

npm run format

Architecture

The project follows a clean architecture approach with distinct layers:

1. Domain Layer: Core entities and business logic
2. Infrastructure Layer: GitHub API integration
3. Service Layer: Business logic coordination
4. MCP Layer: Tool definitions and request handling

For more details, see ARCHITECTURE.md.

License

MIT