---

💡 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)

$3

``bash
npm install github-mcp
`

Or install globally:

`bash
npm install -g github-mcp
`

$3

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

$3

`bash


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!

$3

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

`bash
npx github-mcp streamableHttp
`

Or enable it via environment variables:

`bash
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

$3

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
`

$3

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

$3

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

---

🛠️ Core Features

$3

| Feature | Description | Status |
|---------|-------------|--------|
| 🔍 List Issues | Query Issues list for any repository | ✅ Available |
| 📊 Issue Details | Get complete information for a single Issue | ✅ Available |
| 🔐 Secure Authentication | Safe access based on GitHub Token | ✅ Available |
| ⚙️ Flexible Configuration | Support environment variables and code configuration | ✅ Available |
| 🎨 Object-Oriented Design | Clear class structure, easy to extend | ✅ Available |

$3

| Feature | Description | Estimated Time |
|---------|-------------|----------------|
| ✏️ Create Issue | Quickly create Issues through AI | Q1 2026 |
| 🏷️ Label Management | Add, delete, modify Issue labels | Q1 2026 |
| 💬 Comment Feature | Comment on Issues and PRs | Q1 2026 |
| 🔀 Pull Request | Complete PR management functionality | Q2 2026 |
| 🤖 GitHub Actions | Trigger and monitor workflows | Q2 2026 |
| 📈 Data Analytics | Issue trends and statistical analysis | Q2 2026 |

---

📚 Detailed Usage Guide

$3

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:

`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!

$3

If you want to use it in your own project:

`typescript
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!');
`

$3

GitHubMCPServer supports the following configuration:

`typescript
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

$3

List Issues in a specified repository

Input Parameters:
`typescript
{
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:
`typescript
{
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:
`typescript
// 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

$3

`
┌─────────────────────────────────────┐
│ 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) │
└─────────────────────────────────────┘
`

$3

- 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

$3

`bash


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
`

$3

`
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
`

$3

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:

`typescript
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

$3

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

$3

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

$3

A: Yes! Just configure a custom API address:

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

$3

A: Use the demo file for testing:

`bash


Set Token

export GITHUB_ACCESS_TOKEN="your_token"

Run test

npx tsx demo.ts
`

$3

A: GitHub API has rate limits:
- Unauthenticated: 60 requests/hour
- Authenticated: 5000 requests/hour

Recommended to use Token for higher quota.

---

📊 Roadmap

$3

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

$3

- [ ] Create and update Issues
- [ ] Issue comment functionality
- [ ] Label management
- [ ] Search functionality optimization

$3

- [ ] Full Pull Request support
- [ ] GitHub Actions integration
- [ ] Webhook support
- [ ] Batch operation functionality

$3

- [ ] 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...
``

---