GitHub MCP Server - AI-powered Model Context Protocol server with JAEGIS AI documentation intelligence, natural language workflows, and 57+ comprehensive GitHub tools
npm install jaegis-github-mcp-server> AI-powered GitHub automation with 57+ tools, JAEGIS AI documentation intelligence, and natural language workflows
- Authentication: docs/authentication.md
- API Reference: docs/api-reference.md
- Security: docs/security.md
- Upgrade Guide: docs/upgrade.md
- Examples: examples/
``bashList all available tools
npx jaegis-github-mcp-server@latest --list-tools --format=table
$3
bash
npm install -g jaegis-github-mcp-server
github-mcp-server --list-tools
`📊 Tool Inventory (57 Tools)
| Category | Tools | Description |
| ---------------------------------------- | ----- | ---------------------------------------------------------- |
| Repository Management | 5 | Create, update, delete, list repositories |
| File Operations | 4 | CRUD operations for files in repositories |
| Branch Management | 3 | Create, list, delete branches |
| Pull Requests | 3 | Create, list, merge pull requests |
| Issues | 3 | Create, list, update issues |
| Advanced Repository Management | 9 | Bulk ops, sync, merge repositories, cross-account transfer |
| JAEGIS AI Documentation Intelligence | 5 | AI-powered analysis and insights |
| GitHub Actions & CI/CD | 17 | Workflows, runs, pages, triggers, marketplace listing |
| Repository Security | 7 | Secrets, environments, protections |
| Natural Language Workflows | 1 | Execute complex workflows with natural language |
$3
-
- Create new repositories with configuration
- get_file / create_file / update_file / delete_file - File operations
- create_branch / list_branches / delete_branch - Branch management
- create_pull_request / merge_pull_request - PR workflows
- create_issue / list_issues / update_issue - Issue management$3
-
reorganize_repository - Smart repository restructuring
- bulk_upload_with_structure - Multi-file uploads with directory structure
- batch_file_operations - Coordinated multi-file operations
- sync_local_to_remote - Bidirectional synchronization
- merge_repositories - Multi-repository consolidation
- cross_account_transfer - Cross-account repository transfers$3
-
analyze_documentation_quality - AI-powered documentation analysis
- track_development_velocity - Development metrics with AI insights
- monitor_repository_intelligence - Intelligent repository monitoring
- analyze_dependencies_intelligence - Smart dependency analysis
- generate_mermaid_diagrams - AI-powered diagram generation🔧 Environment Setup
$3
`ini
~/.mcp/.env (Unix) or %USERPROFILE%\.mcp\.env (Windows)
GITHUB_AUTH_MODE=app
GITHUB_APP_ID=YOUR_APP_ID
GITHUB_APP_INSTALLATION_ID=YOUR_INSTALLATION_ID
Choose exactly one private key source:
GITHUB_APP_PRIVATE_KEY_PATH=~/.mcp/private-key.pem
GITHUB_APP_PRIVATE_KEY_BASE64=BASE64_ENCODED_PEM
GITHUB_APP_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----
GITHUB_USERNAME=your-username
GITHUB_EMAIL=user@example.com
`Validation (as of 5 September 2025):
bash
npx jaegis-github-mcp-server@latest --config-check
`Expected (sanitized):
json
{
"server": "github-mcp-server",
"auth_mode": "app",
"authOk": true,
"login": "your-username-or-org",
"installation_id": "YOUR_INSTALLATION_ID"
}
`$3
bash
export GITHUB_TOKEN=ghp_*...*
export GITHUB_USERNAME=your-username
export GITHUB_EMAIL=user@example.com
`$3
- ✅
- Personal access token
- ✅ github_pat_* - Fine-grained personal access token
- ❌ Other formats will show warnings🎯 MCP Client Integration
$3
`json
{
"github": {
"command": "npx",
"args": ["jaegis-github-mcp-server@latest"],
"env": {
"GITHUB_TOKEN": "ghp_*...*",
"GITHUB_USERNAME": "your-username",
"GITHUB_EMAIL": "user@example.com"
}
}
}
`$3
json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["jaegis-github-mcp-server@latest"],
"env": {
"GITHUB_TOKEN": "ghp_*...*",
"GITHUB_USERNAME": "your-username"
}
}
}
}
`📖 Usage Examples
$3
javascript
// Create a new repository
{
"tool": "create_repository",
"parameters": {
"name": "my-new-repo",
"description": "A new repository",
"private": false,
"auto_init": true
}
}
`$3
javascript
// Create a new file
{
"tool": "create_file",
"parameters": {
"owner": "username",
"repo": "repository",
"path": "src/index.js",
"content": "console.log('Hello World');",
"message": "Add initial index.js"
}
}
`$3
javascript
// Analyze documentation quality
{
"tool": "analyze_documentation_quality",
"parameters": {
"owner": "username",
"repo": "repository",
"generate_improvements": true
}
}
`🛠️ Command Line Options
bash
github-mcp-server [OPTIONS]OPTIONS:
--list-tools List all available tools with descriptions
--tools-json Output complete MCP tools schema as JSON
--format=table Use table format for tool listings (default: JSON)
--config-check Validate authentication and print a JSON report
--help, -h Show this help message
EXAMPLES:
github-mcp-server --list-tools --format=table
github-mcp-server --tools-json > tools-schema.json
github-mcp-server --config-check
github-mcp-server # Start MCP server
`🔒 Security Features
- ✅ Credential Sanitization - Sensitive values masked in logs
- ✅ Environment-based Authentication - No hardcoded credentials
- ✅ Token Format Validation - Validates GitHub token formats
- ✅ Multi-account Support - Secure account switching
- ✅ Error Handling - Comprehensive error messages without credential exposure
🚨 Troubleshooting
$3
- Cause: Using GET /user with installation tokens returns 403. Fixed by validating via installation endpoints and App JWT.
- Validate and expect success:
- Upgrading? See Upgrade Guide for details.
bash
npx jaegis-github-mcp-server@latest --config-check
`Expected (sanitized):
json
{
"auth_mode": "app",
"authOk": true,
"login": "your-username-or-org"
}
`$3
"GitHub token is required"
bash
PAT mode
export GITHUB_TOKEN=ghp_*...*
`"API rate limit exceeded"
- Use authenticated requests (token required)
- Wait for rate limit reset
- Consider GitHub Apps for higher limits
"Repository not found"
- Check repository name and owner
- Verify token has access to the repository
- Ensure repository exists and is accessible
"Permission denied"
- Verify token has required scopes
- Check repository permissions
- Ensure token is not expired
📦 Package Information
- Package:
- Version: 3.3.1
- Node.js: >=22.19.0
- License: MIT🧭 Architecture Diagrams
$3
mermaid
flowchart LR
subgraph PAT[ PAT Mode ]
P1[Env: GITHUB_TOKEN] --> P2[Octokit: users.getAuthenticated]
P2 --> P3{200 OK?}
P3 -- Yes --> P4[authOk=true, login=user]
P3 -- No --> P5[authOk=false, error]
end
subgraph APP[ GitHub App Mode ]
A1[Env: APP_ID, INSTALLATION_ID, PRIVATE_KEY] --> A2[App JWT Client]
A1 --> A3[Installation Client]
A3 --> A4[GET /installation/repositories]
A4 --> A5{200 OK?}
A5 -- Yes --> A6[apps.getInstallation]
A6 --> A7[authOk=true, login=installation.account.login]
A5 -- No --> A8[authOk=false, error]
end
`$3
mermaid
flowchart TB
A[Tools] --> B[Repository Management]
A --> C[File Operations]
A --> D[Branch Management]
A --> E[Pull Requests]
A --> F[Issues]
A --> G[Advanced Repository Management]
A --> H[GitHub Actions & CI/CD]
A --> I[Repository Security]
A --> J[Natural Language Workflows]
`$3
mermaid
sequenceDiagram
participant Client as MCP Client
participant Server as jaegis-github-mcp-server
Client->>Server: initialize (stdio)
Server-->>Client: tool list / capabilities
Client->>Server: callTool(create_repository, params)
Server-->>Client: result / error
`$3
mermaid
flowchart TD
Z[Configuration Sources] -->|highest| A[%USERPROFILE%/.mcp/.env]
Z --> B[%APPDATA%/github-mcp-server/.env]
Z --> C[%USERPROFILE%/.config/github-mcp-server/.env]
Z --> D[package .env]
Z -->|lowest| E[cwd .env]
A & B & C & D & E --> F[Resolved config]
F --> G[Auth mode: PAT or App]
``1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
MIT License - see LICENSE file for details.
---
Built with ❤️ by the JAEGIS Team
For more information, visit JAEGIS Documentation