github-mcp-server

GitHub MCP Server for Cursor IDE

A powerful GitHub integration server that allows you to manage your GitHub repositories directly from Cursor IDE. This server provides a RESTful API to interact with GitHub's API, making it easier to create and manage repositories.

Features

• Create new GitHub repositories
• List existing repositories
• Secure token-based authentication
• Rate limiting protection
• Comprehensive error handling
• Detailed logging
• Webhook support (coming soon)

Prerequisites

• Node.js (v14 or higher)
• npm (v6 or higher)
• A GitHub account with a Personal Access Token
• Cursor IDE

Setup

1. Clone this repository:

git clone <your-repo-url>
cd github-mcp-server

2. Install dependencies:

npm install

3. Create a .env file in the root directory:

cp .env.example .env

4. Configure your environment variables in .env:

# Server Configuration
PORT=3000
NODE_ENV=development

# GitHub Configuration
GITHUB_TOKEN=your_github_token_here
GITHUB_WEBHOOK_SECRET=your_webhook_secret_here

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000  # 15 minutes
RATE_LIMIT_MAX_REQUESTS=100

5. Generate a GitHub Personal Access Token:

   • Go to GitHub.com → Settings → Developer Settings → Personal Access Tokens → Tokens (classic)
   • Click "Generate new token" → "Generate new token (classic)"
   • Give your token a descriptive name (e.g., "MCP Server Integration")
   • Select these permissions:
     • repo (Full control of private repositories)
     • read:org (Read organization data)
     • admin:repo_hook (Full control of repository hooks)
   • Copy the generated token and paste it in your .env file

6. Start the server:

npm run dev

Using with Cursor IDE

1. Open Cursor IDE
2. The MCP server will run on http://localhost:3000 by default
3. You can use the following endpoints:

Create a New Repository

curl -X POST http://localhost:3000/api/github/repos \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-repo",
    "description": "A new repository created via MCP",
    "private": false,
    "auto_init": true
  }'

List Your Repositories

curl http://localhost:3000/api/github/repos

API Endpoints

GET /health

Health check endpoint to verify server status.

GET /api/github/repos

Lists all repositories accessible to the authenticated user.

POST /api/github/repos

Creates a new repository.

Request body:

{
  "name": "repository-name",
  "description": "Repository description",
  "private": false,
  "auto_init": true
}

Error Handling

The server includes comprehensive error handling for:

• Invalid GitHub tokens
• Rate limiting
• Validation errors
• GitHub API errors
• Server errors

All errors are logged and returned with appropriate HTTP status codes.

Security Features

• Token-based authentication
• Rate limiting protection
• Input validation
• Secure environment variable handling
• CORS protection
• Helmet security headers

Development

To run the server in development mode with auto-reload:

npm run dev

To run tests:

npm test

Logging

Logs are stored in:

• error.log: Error-level logs
• combined.log: All logs

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.