A powerful GitHub automation tool that seamlessly connects AI assistants to your GitHub repositories
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
npm install github-mcpOr install globally:
npm install -g github-mcp- Visit GitHub Settings > Personal Access Tokens
- Click "Generate new token (classic)"
- Check
repopermission (for accessing repository information) - Copy the generated Token
# 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!
Need an HTTP/SSE endpoint instead of STDIO? Start the Hono-powered Streamable HTTP server:
npx github-mcp streamableHttpOr enable it via environment variables:
MCP_TRANSPORT=streamableHttp STREAMABLE_HTTP_PORT=3001 npx github-mcpThe 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.
Traditional Way:
- Open browser
- Log in to GitHub
- Find the repository
- Click Issues tab
- 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
You: Mark all Issues with "bug" in the title as high priority
AI: Added high priority label to 5 Issues
You: Summarize new Issues from yesterday every morning at 9 AM
AI: Scheduled task created, will send daily report via email
| 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 |
| 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 |
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!
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!');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
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'
});┌─────────────────────────────────────┐
│ 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) │
└─────────────────────────────────────┘
- Single Responsibility:
GitHubMCPServerfocuses 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
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
# 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.tsgithub-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
- Add a new private method in
src/server.ts - Register the tool in
registerTools() - Update README documentation
- 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 }
};
}
);
}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
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
A: Yes! Just configure a custom API address:
const server = new GitHubMCPServer({
apiBase: 'https://github.your-company.com/api/v3',
token: 'your_token'
});A: Use the demo file for testing:
# Set Token
export GITHUB_ACCESS_TOKEN="your_token"
# Run test
npx tsx demo.tsA: GitHub API has rate limits:
- Unauthenticated: 60 requests/hour
- Authenticated: 5000 requests/hour
Recommended to use Token for higher quota.
- Basic MCP server framework
- GitHub Issues list query
- Object-oriented architecture design
- TypeScript type support
- Create and update Issues
- Issue comment functionality
- Label management
- Search functionality optimization
- Full Pull Request support
- GitHub Actions integration
- Webhook support
- Batch operation functionality
- Complete GitHub API coverage
- Graphical management interface
- Plugin system
- Multi-account management
Want to participate in development? Check Issues for pending tasks!
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 ❤️
- GitHub: @Seey215
- Issues: Submit Issues
- Discussions: Join Discussion
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...
If this project helps you, please give it a ⭐️ Star!
Made with ❤️ by Seey215