💡 Why GitHub MCP?

Have you ever faced these challenges?

• ❌ Repetitive Work: Manually checking, creating, and updating Issues and Pull Requests every day
• ❌ Low Efficiency: Constantly switching between command line and browser
• ❌ Collaboration Difficulties: Team members need a unified way to operate GitHub

GitHub MCP solves all of this!

✅ Let Claude, ChatGPT and other AI assistants directly operate GitHub
✅ No need to leave the conversation interface, complete tasks with one sentence
✅ Based on Model Context Protocol, secure and reliable
✅ Fully open source, easily extensible with new features

⚡️ Quick Start (3 Steps)

Step 1: Install

npm install github-mcp

Or install globally:

npm install -g github-mcp

Step 2: Get GitHub Token

1. Visit GitHub Settings > Personal Access Tokens
2. Click "Generate new token (classic)"
3. Check repo permission (for accessing repository information)
4. Copy the generated Token

Step 3: Start the Server

# Set environment variable
export GITHUB_ACCESS_TOKEN="your_github_token_here"

# Start the server
npx github-mcp

🎉 Done! Now your AI assistant can operate GitHub!

Alternative Transport: Streamable HTTP (Hono)

Need an HTTP/SSE endpoint instead of STDIO? Start the Hono-powered Streamable HTTP server:

npx github-mcp streamableHttp

Or enable it via environment variables:

MCP_TRANSPORT=streamableHttp STREAMABLE_HTTP_PORT=3001 npx github-mcp

The Hono server exposes /mcp for POST/GET/DELETE requests, automatically handles CORS, and keeps SSE streams open for real-time messaging. It still reuses the same GitHubMCPServer logic from STDIO, so your tools and configuration behave identically.

Tip: You can start the server even without a Token, authentication is only required when calling GitHub APIs.

🎯 Use Cases

Scenario 1: Quickly View Issue List

Traditional Way:

1. Open browser
2. Log in to GitHub
3. Find the repository
4. Click Issues tab
5. Manually filter and view

With GitHub MCP:

You: Help me check what unresolved Issues are in Seey215/github-mcp repository
AI:  Querying... Found 3 unresolved Issues:
     1. #12 - Add Pull Request management feature
     2. #10 - Support GitHub Actions trigger
     3. #8 - Optimize error messages

Scenario 2: Batch Process Issues

You: Mark all Issues with "bug" in the title as high priority
AI:  Added high priority label to 5 Issues

Scenario 3: Automated Workflows

You: Summarize new Issues from yesterday every morning at 9 AM
AI:  Scheduled task created, will send daily report via email

🛠️ Core Features

✅ Currently Available

🚧 Coming Soon

📚 Detailed Usage Guide

Running as MCP Server (Recommended)

This is the most common usage, suitable for integration with AI tools like Claude Desktop, Continue, etc.

Configure Claude Desktop:

Edit the configuration file ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "github-mcp"],
      "env": {
        "GITHUB_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Desktop, and you can use GitHub features in conversations!

Using as Node.js Library

If you want to use it in your own project:

import { GitHubMCPServer } from 'github-mcp';
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Create server instance
const server = new GitHubMCPServer({
  token: 'your_github_token',
  serverName: 'my-custom-server',
  serverVersion: '1.0.0'
});

// Connect transport layer
const transport = new StdioServerTransport();
await server.connect(transport);

console.log('GitHub MCP Server started!');

Configuration Options

GitHubMCPServer supports the following configuration:

interface GitHubConfig {
  token?: string;           // GitHub Personal Access Token
  apiBase?: string;         // API base URL (default: https://api.github.com)
  apiVersion?: string;      // API version (default: 2022-11-28)
  serverName?: string;      // Server name (default: github-mcp-server)
  serverVersion?: string;   // Server version (default: 1.0.0)
}

Configuration Priority: Constructor parameters > Environment variables > Default values

🔧 API Reference

Tool: list_issues

List Issues in a specified repository

Input Parameters:

{
  owner: string;    // Repository owner, e.g., "Seey215"
  repo: string;     // Repository name, e.g., "github-mcp"
  state?: 'open' | 'closed';  // Issue state (optional, default 'open')
}

Return Data:

{
  issues: Array<{
    number: number;        // Issue number
    title: string;         // Title
    body: string | null;   // Description content
    state: 'open' | 'closed';
    user: string;          // Creator
    created_at: string;    // Creation time
    updated_at: string;    // Update time
    html_url: string;      // GitHub page link
  }>
}

Usage Example:

// In AI conversation
"Help me check all Issues in Seey215/github-mcp repository"

// Underlying call
await server.callTool('list_issues', {
  owner: 'Seey215',
  repo: 'github-mcp'
});

🏗️ Architecture Design

Object-Oriented Architecture

┌─────────────────────────────────────┐
│   GitHubMCPServer (Core Class)      │
├─────────────────────────────────────┤
│ - config: GitHubConfig              │
│ - server: McpServer                 │
├─────────────────────────────────────┤
│ + constructor(config?)              │
│ + connect(transport)                │
│ - registerTools()                   │
│ - githubApiRequest(endpoint)        │
└─────────────────────────────────────┘
         │
         │ uses
         ▼
┌─────────────────────────────────────┐
│   MCP SDK (Communication Protocol)  │
│   - StdioServerTransport            │
│   - Tool Registration & Invocation  │
└─────────────────────────────────────┘
         │
         │ calls
         ▼
┌─────────────────────────────────────┐
│   GitHub REST API                   │
│   - Issues                          │
│   - Pull Requests (coming soon)     │
│   - Actions (planned)               │
└─────────────────────────────────────┘

Design Principles

• Single Responsibility: GitHubMCPServer focuses on GitHub API integration
• Encapsulation: Private methods hide implementation details
• Configurability: Flexible constructor supports multiple configuration methods
• Extensibility: Clear structure makes it easy to add new tools
• Lazy Validation: Token is only validated when using API, improving user experience

🤝 Contributing

We warmly welcome community contributions! Whether it's:

• 🐛 Report Bugs: Found an issue? Submit an Issue
• 💡 Suggest Features: Have a great idea? Tell us!
• 🔨 Submit Code: Fork the project, submit a Pull Request
• 📖 Improve Documentation: Help improve docs and examples

Development Environment Setup

# 1. Fork and clone repository
git clone https://github.com/your-username/github-mcp.git
cd github-mcp

# 2. Install dependencies
npm install

# 3. Build project
npm run build

# 4. Start development mode (auto-recompile)
npm run watch

# 5. Run tests
npx tsx demo.ts

Project Structure

github-mcp/
├── src/
│   ├── types.ts              # TypeScript type definitions
│   ├── server.ts             # GitHubMCPServer main class
│   └── index.ts              # Entry file
├── dist/                     # Compiled output directory
├── demo.ts                   # Example and test file
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript configuration
└── README.md                 # Project documentation

Adding New Tools

1. Add a new private method in src/server.ts
2. Register the tool in registerTools()
3. Update README documentation
4. Submit a Pull Request

Example code:

private registerCreateIssueTool(): void {
  this.server.registerTool(
    'create_issue',
    {
      title: 'Create Issue',
      description: 'Create a new issue in a GitHub repository',
      inputSchema: {
        owner: z.string(),
        repo: z.string(),
        title: z.string(),
        body: z.string().optional()
      },
      outputSchema: {
        issue: z.object({
          number: z.number(),
          html_url: z.string()
        })
      }
    },
    async ({ owner, repo, title, body }) => {
      const endpoint = `/repos/${owner}/${repo}/issues`;
      const data = await this.githubApiRequest(endpoint, {
        method: 'POST',
        body: JSON.stringify({ title, body })
      });
      
      return {
        content: [],
        structuredContent: { issue: data }
      };
    }
  );
}

❓ FAQ

Q: Why not validate Token at startup?

A: For better user experience! Even without a Token, you can:

• View all available tools
• Understand each tool's functionality
• Use them when Token is ready

Q: Is the Token secure?

A: Yes! The Token is only stored in local environment variables and is never uploaded or shared. Recommendations:

• Use Fine-grained tokens to limit permission scope
• Rotate Token regularly
• Never hardcode Token in public code

Q: Does it support GitHub Enterprise?

A: Yes! Just configure a custom API address:

const server = new GitHubMCPServer({
  apiBase: 'https://github.your-company.com/api/v3',
  token: 'your_token'
});

Q: How to debug?

A: Use the demo file for testing:

# Set Token
export GITHUB_ACCESS_TOKEN="your_token"

# Run test
npx tsx demo.ts

Q: What about API rate limiting?

A: GitHub API has rate limits:

• Unauthenticated: 60 requests/hour
• Authenticated: 5000 requests/hour

Recommended to use Token for higher quota.

📊 Roadmap

v0.1.0 - Current Version ✅

• Basic MCP server framework
• GitHub Issues list query
• Object-oriented architecture design
• TypeScript type support

v0.2.0 - Next Version 🚧

• Create and update Issues
• Issue comment functionality
• Label management
• Search functionality optimization

v0.3.0 - Future Plans 📋

• Full Pull Request support
• GitHub Actions integration
• Webhook support
• Batch operation functionality

v1.0.0 - Long-term Goals 🎯

• Complete GitHub API coverage
• Graphical management interface
• Plugin system
• Multi-account management

Want to participate in development? Check Issues for pending tasks!

🌟 Acknowledgments

Thanks to the following projects and communities:

• Model Context Protocol - Powerful AI integration protocol
• GitHub REST API - Comprehensive API documentation
• Anthropic Claude - Excellent AI assistant
• All contributors and users ❤️

📞 Contact

• GitHub: @Seey215
• Issues: Submit Issues
• Discussions: Join Discussion

📄 License

This project is licensed under the MIT License.

MIT License

Copyright (c) 2025 Seey215

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...