jaegis-github-mcp-server

AI-powered GitHub automation with 57+ tools, JAEGIS AI documentation intelligence, and natural language workflows

Quick links

• Authentication: docs/authentication.md
• API Reference: docs/api-reference.md
• Security: docs/security.md
• Upgrade Guide: docs/upgrade.md
• Examples: examples/

🚀 Quick Start

NPX (Recommended)

# List all available tools
npx jaegis-github-mcp-server@latest --list-tools --format=table

# Get tools schema for MCP integration
npx jaegis-github-mcp-server@latest --tools-json

# Start the MCP server
npx jaegis-github-mcp-server@latest

Global Installation

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 |

Core Tools

• create_repository - 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

Advanced Tools

• 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

JAEGIS AI Intelligence

• 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

Option A) GitHub App (recommended for orgs)

# ~/.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
[email protected]

Validation (as of 5 September 2025):

npx jaegis-github-mcp-server@latest --config-check

Expected (sanitized):

{
  "server": "github-mcp-server",
  "auth_mode": "app",
  "authOk": true,
  "login": "your-username-or-org",
  "installation_id": "YOUR_INSTALLATION_ID"
}

Option B) Personal Access Token (PAT)

export GITHUB_TOKEN=ghp_****...****
export GITHUB_USERNAME=your-username
export [email protected]

Token Format Validation

• ✅ ghp_* - Personal access token
• ✅ github_pat_* - Fine-grained personal access token
• ❌ Other formats will show warnings

🎯 MCP Client Integration

Augment Code

{
  "github": {
    "command": "npx",
    "args": ["jaegis-github-mcp-server@latest"],
    "env": {
      "GITHUB_TOKEN": "ghp_****...****",
      "GITHUB_USERNAME": "your-username",
      "GITHUB_EMAIL": "[email protected]"
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["jaegis-github-mcp-server@latest"],
      "env": {
        "GITHUB_TOKEN": "ghp_****...****",
        "GITHUB_USERNAME": "your-username"
      }
    }
  }
}

📖 Usage Examples

Repository Management

// Create a new repository
{
  "tool": "create_repository",
  "parameters": {
    "name": "my-new-repo",
    "description": "A new repository",
    "private": false,
    "auto_init": true
  }
}

File Operations

// 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"
  }
}

AI-Powered Analysis

// Analyze documentation quality
{
  "tool": "analyze_documentation_quality",
  "parameters": {
    "owner": "username",
    "repo": "repository",
    "generate_improvements": true
  }
}

🛠️ Command Line Options

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

GitHub App config-check shows authOk: false (fixed in v3.3.1)

• 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.

npx jaegis-github-mcp-server@latest --config-check

Expected (sanitized):

{
  "auth_mode": "app",
  "authOk": true,
  "login": "your-username-or-org"
}

Common Issues

"GitHub token is required"

# 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: jaegis-github-mcp-server
• Version: 3.3.1
• Node.js: >=22.19.0
• License: MIT

🧭 Architecture Diagrams

Authentication flows (PAT vs GitHub App)

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

Tool categorization

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]

MCP client integration (stdio)

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

Configuration loading hierarchy

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]

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ by the JAEGIS Team

For more information, visit JAEGIS Documentation