# mcp-server-github

[![npm version](https://badge.fury.io/js/mcp-server-github.svg)](https://www.npmjs.com/package/mcp-server-github)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub Sponsors](https://img.shields.io/github/sponsors/DebuggingMax)](https://github.com/sponsors/DebuggingMax)

A **Model Context Protocol (MCP)** server that enables AI assistants like Claude to interact with the GitHub API directly.

## 🚀 Features

- **Issues Management** - List, create, update, and comment on issues
- **Pull Requests** - Create PRs, review code, merge changes
- **Repository Operations** - Search repos, get file contents, commit files
- **Code Search** - Search code across GitHub
- **Notifications** - List and manage your GitHub notifications
- **User Profiles** - Get user and organization info

## 📦 Installation

```bash
npm install -g mcp-server-github
```

Or use directly with npx:

```bash
npx mcp-server-github
```

## ⚙️ Configuration

### 1. Get a GitHub Token

Create a [Personal Access Token](https://github.com/settings/tokens) with the following scopes:
- `repo` - Full control of private repositories
- `read:user` - Read user profile data
- `notifications` - Access notifications

### 2. Set Environment Variable

```bash
export GITHUB_TOKEN=your_token_here
# or
export GH_TOKEN=your_token_here
```

### 3. Configure Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}
```

## 🛠️ Available Tools

### Issues
| Tool | Description |
|------|-------------|
| `list_issues` | List issues in a repository |
| `get_issue` | Get a specific issue by number |
| `create_issue` | Create a new issue |
| `update_issue` | Update an existing issue |
| `add_issue_comment` | Add a comment to an issue |

### Pull Requests
| Tool | Description |
|------|-------------|
| `list_pull_requests` | List PRs in a repository |
| `get_pull_request` | Get a specific PR |
| `create_pull_request` | Create a new PR |
| `create_review` | Review a PR (approve/request changes) |
| `merge_pull_request` | Merge a PR |

### Repository
| Tool | Description |
|------|-------------|
| `get_repository` | Get repository information |
| `list_repositories` | List user/org repositories |
| `search_repositories` | Search for repositories |
| `get_file_contents` | Get file contents |
| `create_or_update_file` | Create or update a file |

### Code Search
| Tool | Description |
|------|-------------|
| `search_code` | Search code across GitHub |

### Notifications
| Tool | Description |
|------|-------------|
| `list_notifications` | List notifications |
| `mark_notifications_read` | Mark all as read |

### User
| Tool | Description |
|------|-------------|
| `get_authenticated_user` | Get your profile |
| `get_user` | Get any user's profile |

## 💡 Usage Examples

Once configured, you can ask Claude:

> "List all open issues in my project"

> "Create a PR from feature-branch to main with a summary of changes"

> "Search for TypeScript files containing 'authentication' in my repos"

> "Show me my unread GitHub notifications"

---

## 💎 Pro Features

Take your GitHub integration to the next level with **Pro features**:

### 🏢 Pro Plan
- **Organization-wide Permissions** - Manage permissions across all org repos
- **Webhook Support** - Real-time event notifications and custom endpoints
- **Advanced Search** - Search across organizations with filters and analytics
- **Priority Support** - Direct support channel

### 🏗️ Enterprise Plan
- Everything in Pro, plus:
- **Self-hosted Deployment** - Run on your own infrastructure
- **SSO/SAML Integration** - Enterprise authentication
- **Audit Logs** - Complete activity tracking
- **Custom Integrations** - Tailored to your workflow
- **SLA Guarantee** - 99.9% uptime commitment

[**👉 View Enterprise Features**](./docs/ENTERPRISE.md)

### 💖 Support Development

If you find this project useful, consider [becoming a sponsor](https://github.com/sponsors/DebuggingMax)!

Your sponsorship helps:
- Maintain and improve the project
- Add new features
- Provide better documentation
- Keep it free and open source

[![Sponsor](https://img.shields.io/badge/Sponsor-❤️-red)](https://github.com/sponsors/DebuggingMax)

---

## 🔧 Development

```bash
# Clone the repo
git clone https://github.com/DebuggingMax/mcp-server-github.git
cd mcp-server-github

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start
```

## 📝 License

MIT License - see [LICENSE](LICENSE) for details.

## 🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

Made with ❤️ by [DebuggingMax](https://github.com/DebuggingMax)