GitHub MCP Server
A Model Context Protocol (MCP) server that provides GitHub integration capabilities, specifically for creating GitHub issues through the MCP interface.
Overview
This MCP server allows AI assistants and other MCP clients to interact with GitHub repositories by creating issues and exploring repositories/documentation. It implements the MCP protocol to provide a standardized interface for GitHub operations.
Features
- Create GitHub Issues: Create new issues in GitHub repositories
- Discover Repositories: List user/org repos and search public repos
- Read Documentation: Fetch README and markdown docs, or arbitrary files
- Input Validation: Robust parameter validation using Zod schemas
- Error Handling: Comprehensive error handling with proper MCP error codes
- Type Safety: Full TypeScript implementation with strict type checking
Prerequisites
- Node.js (v18 or higher)
- npm or yarn
- GitHub Personal Access Token
Installation
- Clone the repository:```bash
git clone <repository-url>
cd git_mcp
2. Install dependencies:```bash
npm install
- Set up environment variables:```bash
cp .env.example .env
4. Edit `.env` and add your GitHub token:```
GITHUB_TOKEN=your_github_token_here
Configuration
GitHub Token Setup
- Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
- Generate a new token with the following scopes:
-repo(Full control of private repositories)
-public_repo(Access public repositories) - Copy the token and add it to your
.envfile
Environment Variables
| Variable | Description | Required |
|---|---|---|
GITHUB_TOKEN |
Your GitHub Personal Access Token | Yes |
Usage
Development Mode
Run the server in development mode with hot reloading:```bash
npm run dev
### Production Mode
1. Build the project:```bash
npm run build
- Start the server:```bash
npm start
### MCP Client Integration
The server communicates via stdio transport, making it compatible with any MCP client. Here's how to configure it in your MCP client:```json
{
"mcpServers": {
"github": {
"command": "node",
"args": ["dist/github-mcp-server.js"],
"env": {
"GITHUB_TOKEN": "your_token_here"
}
}
}
}
API Reference
Available Tools
create-issue
Creates a new GitHub issue in a specified repository.
Parameters:
- title (string, required): The title of the issue
- body (string, optional): The body/description of the issue
- owner (string, required): The repository owner (username or organization)
- repo (string, required): The repository name
- labels (array of strings, optional): Labels to add to the issue
- assignees (array of strings, optional): Usernames to assign to the issue
Example Usage:```json
{
"name": "create-issue",
"arguments": {
"title": "Fix login bug",
"body": "Users are unable to log in with their credentials",
"owner": "myorg",
"repo": "myproject",
"labels": ["bug", "high-priority"],
"assignees": ["developer1"]
}
}
**Response:**```json
{
"content": [
{
"type": "text",
"text": "Successfully created issue #123: Fix login bug\nURL: https://github.com/myorg/myproject/issues/123"
}
]
}
list-user-repos
Lists repositories for a user or the authenticated user.
Parameters:
- username (string, optional): If omitted, lists repos for the authenticated user
- visibility ("all" · "public" · "private", optional, default "all")
- per_page (integer, 1-100, default 50)
- page (integer, default 1)
Example:```json
{ "name": "list-user-repos", "arguments": { "visibility": "public" } }
#### list-org-repos
Lists repositories in an organization.
**Parameters:**
- `org` (string, required)
- `type` ("all" · "public" · "private" · "forks" · "sources" · "member", default "all")
- `per_page` (integer, 1-100, default 50)
- `page` (integer, default 1)
**Example:**```json
{ "name": "list-org-repos", "arguments": { "org": "myorg", "type": "public" } }
search-repos
Searches public repositories using GitHub search syntax.
Parameters:
- q (string, required): Query, e.g. "lang:ts topic:mcp sdk"
- sort ("stars" · "forks" · "help-wanted-issues" · "updated")
- order ("desc" | "asc", default "desc")
- per_page (integer, 1-100, default 30)
- page (integer, default 1)
Example:```json
{ "name": "search-repos", "arguments": { "q": "mcp in:name language:TypeScript" } }
#### get-readme
Fetches the README file as text from a repository.
**Parameters:**
- `owner` (string, required)
- `repo` (string, required)
- `ref` (string, optional): Branch, tag, or SHA
**Example:**```json
{ "name": "get-readme", "arguments": { "owner": "myorg", "repo": "myrepo" } }
list-docs
Lists markdown documentation files in common docs directories and root.
Parameters:
- owner (string, required)
- repo (string, required)
- ref (string, optional)
Example:```json
{ "name": "list-docs", "arguments": { "owner": "myorg", "repo": "myrepo" } }
#### get-file
Fetches an arbitrary repository file as text.
**Parameters:**
- `owner` (string, required)
- `repo` (string, required)
- `path` (string, required)
- `ref` (string, optional)
**Example:**```json
{ "name": "get-file", "arguments": { "owner": "myorg", "repo": "myrepo", "path": "docs/intro.md" } }
Error Handling
The server implements comprehensive error handling:
- Invalid Parameters: Returns
InvalidParamserror code with detailed validation messages - GitHub API Errors: Returns
InternalErrorwith GitHub API error details - Authentication Errors: Returns
InternalErrorwhen GitHub token is invalid - Unknown Tools: Returns
MethodNotFoundfor unsupported tool requests
Development
Project Structure```
src/
├── github-mcp-server.ts # Main server implementation
package.json # Dependencies and scripts
tsconfig.json # TypeScript configuration
README.md # This documentation
### Key Components
1. **GitHubMCPServer Class**: Main server class that handles MCP protocol
2. **Schema Validation**: Uses Zod for robust parameter validation
3. **Error Handling**: Comprehensive error handling with proper MCP error codes
4. **Transport Layer**: Uses stdio transport for MCP communication
### Code Changes Made
#### 1. Fixed Syntax Error
**Problem**: Double `this` keyword on line 34```typescript
// Before (incorrect)
this this.server.setRequestHandler(...)
// After (correct)
this.server.setRequestHandler(...)
2. Added Schema Definition
Problem: Missing CreateIssueRequestSchema definition
Solution: Created comprehensive Zod schema with validation:```typescript
const CreateIssueRequestSchema = z.object({
title: z.string().describe("The title of the issue"),
body: z.string().optional().describe("The body/description of the issue"),
owner: z.string().describe("The repository owner (username or organization)"),
repo: z.string().describe("The repository name"),
labels: z.array(z.string()).optional().describe("Labels to add to the issue"),
assignees: z.array(z.string()).optional().describe("Usernames to assign to the issue"),
});
#### 3. Implemented Tool Handler
**Problem**: Empty `handleRequest()` method
**Solution**: Complete implementation with:
- Parameter validation using Zod
- GitHub API integration
- Proper error handling
- MCP-compliant responses
#### 4. Added Server Startup
**Problem**: Server created but never started
**Solution**: Added complete startup sequence:
- Transport initialization
- Server connection
- Main execution function
- Graceful shutdown handling
#### 5. Enhanced Imports
**Problem**: Missing type imports causing linter errors
**Solution**: Separated runtime and type imports:```typescript
import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
import type { Tool, CallToolResult, TextContent } from "@modelcontextprotocol/sdk/types.js";
Dependencies Added
- zod: Runtime schema validation for robust parameter checking
- @types/node: TypeScript definitions for Node.js
Testing
Manual Testing
- Start the server:```bash
npm run dev
2. Test with an MCP client that supports the create-issue tool
### Integration Testing
The server can be tested with any MCP-compliant client by sending proper MCP protocol messages.
## Troubleshooting
### Common Issues
1. **"GITHUB_TOKEN environment variable is required"**
- Ensure your `.env` file contains a valid `GITHUB_TOKEN`
- Verify the token has the required permissions
2. **"Failed to create issue: 404 Not Found"**
- Check that the repository owner and name are correct
- Ensure the token has access to the repository
3. **"Invalid parameters"**
- Verify all required parameters are provided
- Check parameter types match the schema
### Debug Mode
Enable debug logging by setting the `DEBUG` environment variable:```bash
DEBUG=* npm run dev
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
ISC License - see LICENSE file for details
Support
For issues and questions:
1. Check the troubleshooting section
2. Review GitHub API documentation
3. Open an issue in the repository
Changelog
v1.0.0
- Initial release
- GitHub issue creation functionality
- MCP protocol compliance
- Comprehensive error handling
- TypeScript implementation
