Environment Variables (Recommended)

To keep your GitHub PAT secure and reusable across different MCP hosts:

1. Store your PAT in environment variables

   export GITHUB_PAT=your_token_here
   

   Or create a .env file:

   GITHUB_PAT=your_token_here
   

2. Protect your .env file

   # Add to .gitignore to prevent accidental commits
   echo ".env" >> .gitignore
   

3. Reference the token in configurations

   # CLI usage
   claude mcp update github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT
   
   # In config files (where supported)
   "env": {
     "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT"
   }
   

Note: Environment variable support varies by host app and IDE. Some applications (like Windsurf) require hardcoded tokens in config files.

Token Security Best Practices

• Minimum scopes: Only grant necessary permissions

  • repo - Repository operations
  • read:packages - Docker image access
  • read:org - Organization team access

• Separate tokens: Use different PATs for different projects/environments

• Regular rotation: Update tokens periodically

• Never commit: Keep tokens out of version control

• File permissions: Restrict access to config files containing tokens

  chmod 600 ~/.your-app/config.json
  

{
  "inputs": [
    {
      "type": "promptString",
      "id": "github_token",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
      }
    }
  }
}

Actions

• actions_get - Get details of GitHub Actions resources (workflows, workflow runs, jobs, and artifacts)

  • Required OAuth Scopes: repo
  • method: The method to execute (string, required)
  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)
  • resource_id: The unique identifier of the resource. This will vary based on the "method" provided, so ensure you provide the correct ID:
    • Provide a workflow ID or workflow file name (e.g. ci.yaml) for 'get_workflow' method.
    • Provide a workflow run ID for 'get_workflow_run', 'get_workflow_run_usage', and 'get_workflow_run_logs_url' methods.
    • Provide an artifact ID for 'download_workflow_run_artifact' method.
    • Provide a job ID for 'get_workflow_job' method. (string, required)

• actions_list - List GitHub Actions workflows in a repository

  • Required OAuth Scopes: repo
  • method: The action to perform (string, required)
  • owner: Repository owner (string, required)
  • page: Page number for pagination (default: 1) (number, optional)
  • per_page: Results per page for pagination (default: 30, max: 100) (number, optional)
  • repo: Repository name (string, required)
  • resource_id: The unique identifier of the resource. This will vary based on the "method" provided, so ensure you provide the correct ID:
    • Do not provide any resource ID for 'list_workflows' method.
    • Provide a workflow ID or workflow file name (e.g. ci.yaml) for 'list_workflow_runs' method, or omit to list all workflow runs in the repository.
    • Provide a workflow run ID for 'list_workflow_jobs' and 'list_workflow_run_artifacts' methods. (string, optional)
  • workflow_jobs_filter: Filters for workflow jobs. ONLY used when method is 'list_workflow_jobs' (object, optional)
  • workflow_runs_filter: Filters for workflow runs. ONLY used when method is 'list_workflow_runs' (object, optional)

• actions_run_trigger - Trigger GitHub Actions workflow actions

  • Required OAuth Scopes: repo
  • inputs: Inputs the workflow accepts. Only used for 'run_workflow' method. (object, optional)
  • method: The method to execute (string, required)
  • owner: Repository owner (string, required)
  • ref: The git reference for the workflow. The reference can be a branch or tag name. Required for 'run_workflow' method. (string, optional)
  • repo: Repository name (string, required)
  • run_id: The ID of the workflow run. Required for all methods except 'run_workflow'. (number, optional)
  • workflow_id: The workflow ID (numeric) or workflow file name (e.g., main.yml, ci.yaml). Required for 'run_workflow' method. (string, optional)

• get_job_logs - Get GitHub Actions workflow job logs

  • Required OAuth Scopes: repo
  • failed_only: When true, gets logs for all failed jobs in the workflow run specified by run_id. Requires run_id to be provided. (boolean, optional)
  • job_id: The unique identifier of the workflow job. Required when getting logs for a single job. (number, optional)
  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)
  • return_content: Returns actual log content instead of URLs (boolean, optional)
  • run_id: The unique identifier of the workflow run. Required when failed_only is true to get logs for all failed jobs in the run. (number, optional)
  • tail_lines: Number of lines to return from the end of the log (number, optional)

Code Security

• get_code_scanning_alert - Get code scanning alert

  • Required OAuth Scopes: security_events
  • Accepted OAuth Scopes: repo, security_events
  • alertNumber: The number of the alert. (number, required)
  • owner: The owner of the repository. (string, required)
  • repo: The name of the repository. (string, required)

• list_code_scanning_alerts - List code scanning alerts

  • Required OAuth Scopes: security_events
  • Accepted OAuth Scopes: repo, security_events
  • owner: The owner of the repository. (string, required)
  • ref: The Git reference for the results you want to list. (string, optional)
  • repo: The name of the repository. (string, required)
  • severity: Filter code scanning alerts by severity (string, optional)
  • state: Filter code scanning alerts by state. Defaults to open (string, optional)
  • tool_name: The name of the tool used for code scanning. (string, optional)

Context

• get_me - Get my user profile

  • No parameters required

• get_team_members - Get team members

  • Required OAuth Scopes: read:org
  • Accepted OAuth Scopes: admin:org, read:org, write:org
  • org: Organization login (owner) that contains the team. (string, required)
  • team_slug: Team slug (string, required)

• get_teams - Get teams

  • Required OAuth Scopes: read:org
  • Accepted OAuth Scopes: admin:org, read:org, write:org
  • user: Username to get teams for. If not provided, uses the authenticated user. (string, optional)

Copilot

• assign_copilot_to_issue - Assign Copilot to issue

  • Required OAuth Scopes: repo
  • base_ref: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch (string, optional)
  • custom_instructions: Optional custom instructions to guide the agent beyond the issue body. Use this to provide additional context, constraints, or guidance that is not captured in the issue description (string, optional)
  • issue_number: Issue number (number, required)
  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)

• request_copilot_review - Request Copilot review

  • Required OAuth Scopes: repo
  • owner: Repository owner (string, required)
  • pullNumber: Pull request number (number, required)
  • repo: Repository name (string, required)

Dependabot

• get_dependabot_alert - Get dependabot alert

  • Required OAuth Scopes: security_events
  • Accepted OAuth Scopes: repo, security_events
  • alertNumber: The number of the alert. (number, required)
  • owner: The owner of the repository. (string, required)
  • repo: The name of the repository. (string, required)

• list_dependabot_alerts - List dependabot alerts

  • Required OAuth Scopes: security_events
  • Accepted OAuth Scopes: repo, security_events
  • owner: The owner of the repository. (string, required)
  • repo: The name of the repository. (string, required)
  • severity: Filter dependabot alerts by severity (string, optional)
  • state: Filter dependabot alerts by state. Defaults to open (string, optional)

Discussions

• get_discussion - Get discussion

  • Required OAuth Scopes: repo
  • discussionNumber: Discussion Number (number, required)
  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)

• get_discussion_comments - Get discussion comments

  • Required OAuth Scopes: repo
  • after: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
  • discussionNumber: Discussion Number (number, required)
  • owner: Repository owner (string, required)
  • perPage: Results per page for pagination (min 1, max 100) (number, optional)
  • repo: Repository name (string, required)

• list_discussion_categories - List discussion categories

  • Required OAuth Scopes: repo
  • owner: Repository owner (string, required)
  • repo: Repository name. If not provided, discussion categories will be queried at the organisation level. (string, optional)

• list_discussions - List discussions

  • Required OAuth Scopes: repo
  • after: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
  • category: Optional filter by discussion category ID. If provided, only discussions with this category are listed. (string, optional)
  • direction: Order direction. (string, optional)
  • orderBy: Order discussions by field. If provided, the 'direction' also needs to be provided. (string, optional)
  • owner: Repository owner (string, required)
  • perPage: Results per page for pagination (min 1, max 100) (number, optional)
  • repo: Repository name. If not provided, discussions will be queried at the organisation level. (string, optional)

Gists

• create_gist - Create Gist

  • Required OAuth Scopes: gist
  • content: Content for simple single-file gist creation (string, required)
  • description: Description of the gist (string, optional)
  • filename: Filename for simple single-file gist creation (string, required)
  • public: Whether the gist is public (boolean, optional)

• get_gist - Get Gist Content

  • gist_id: The ID of the gist (string, required)

• list_gists - List Gists

  • page: Page number for pagination (min 1) (number, optional)
  • perPage: Results per page for pagination (min 1, max 100) (number, optional)
  • since: Only gists updated after this time (ISO 8601 timestamp) (string, optional)
  • username: GitHub username (omit for authenticated user's gists) (string, optional)

• update_gist - Update Gist

  • Required OAuth Scopes: gist
  • content: Content for the file (string, required)
  • description: Updated description of the gist (string, optional)
  • filename: Filename to update or create (string, required)
  • gist_id: ID of the gist to update (string, required)

Git

• get_repository_tree - Get repository tree
  • Required OAuth Scopes: repo
  • owner: Repository owner (username or organization) (string, required)
  • path_filter: Optional path prefix to filter the tree results (e.g., 'src/' to only show files in the src directory) (string, optional)
  • recursive: Setting this parameter to true returns the objects or subtrees referenced by the tree. Default is false (boolean, optional)
  • repo: Repository name (string, required)
  • tree_sha: The SHA1 value or ref (branch or tag) name of the tree. Defaults to the repository's default branch (string, optional)

Issues

• add_issue_comment - Add comment to issue

  • Required OAuth Scopes: repo
  • body: Comment content (string, required)
  • issue_number: Issue number to comment on (number, required)
  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)

• get_label - Get a specific label from a repository.

  • Required OAuth Scopes: repo
  • name: Label name. (string, required)
  • owner: Repository owner (username or organization name) (string, required)
  • repo: Repository name (string, required)

• issue_read - Get issue details

  • Required OAuth Scopes: repo
  • issue_number: The number of the issue (number, required)
  • method: The read operation to perform on a single issue. Options are:
    1. get - Get details of a specific issue.
    2. get_comments - Get issue comments.
    3. get_sub_issues - Get sub-issues of the issue.
    4. get_labels - Get labels assigned to the issue. (string, required)
  • owner: The owner of the repository (string, required)
  • page: Page number for pagination (min 1) (number, optional)
  • perPage: Results per page for pagination (min 1, max 100) (number, optional)
  • repo: The name of the repository (string, required)

• issue_write - Create or update issue.

  • Required OAuth Scopes: repo
  • assignees: Usernames to assign to this issue (string[], optional)
  • body: Issue body content (string, optional)
  • duplicate_of: Issue number that this issue is a duplicate of. Only used when state_reason is 'duplicate'. (number, optional)
  • issue_number: Issue number to update (number, optional)
  • labels: Labels to apply to this issue (string[], optional)
  • method: Write operation to perform on a single issue. Options are:
    • 'create' - creates a new issue.
    • 'update' - updates an existing issue. (string, required)
  • milestone: Milestone number (number, optional)
  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)
  • state: New state (string, optional)
  • state_reason: Reason for the state change. Ignored unless state is changed. (string, optional)
  • title: Issue title (string, optional)
  • type: Type of this issue. Only use if the repository has issue types configured. Use list_issue_types tool to get valid type values for the organization. If the repository doesn't support issue types, omit this parameter. (string, optional)

• list_issue_types - List available issue types

  • Required OAuth Scopes: read:org
  • Accepted OAuth Scopes: admin:org, read:org, write:org
  • owner: The organization owner of the repository (string, required)

• list_issues - List issues

  • Required OAuth Scopes: repo
  • after: Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs. (string, optional)
  • direction: Order direction. If provided, the 'orderBy' also needs to be provided. (string, optional)
  • labels: Filter by labels (string[], optional)
  • orderBy: Order issues by field. If provided, the 'direction' also needs to be provided. (string, optional)
  • owner: Repository owner (string, required)
  • perPage: Results per page for pagination (min 1, max 100) (number, optional)
  • repo: Repository name (string, required)
  • since: Filter by date (ISO 8601 timestamp) (string, optional)
  • state: Filter by state, by default both open and closed issues are returned when not provided (string, optional)

• search_issues - Search issues

  • Required OAuth Scopes: repo
  • order: Sort order (string, optional)
  • owner: Optional repository owner. If provided with repo, only issues for this repository are listed. (string, optional)
  • page: Page number for pagination (min 1) (number, optional)
  • perPage: Results per page for pagination (min 1, max 100) (number, optional)
  • query: Search query using GitHub issues search syntax (string, required)
  • repo: Optional repository name. If provided with owner, only issues for this repository are listed. (string, optional)
  • sort: Sort field by number of matches of categories, defaults to best match (string, optional)

• sub_issue_write - Change sub-issue

  • Required OAuth Scopes: repo
  • after_id: The ID of the sub-issue to be prioritized after (either after_id OR before_id should be specified) (number, optional)
  • before_id: The ID of the sub-issue to be prioritized before (either after_id OR before_id should be specified) (number, optional)
  • issue_number: The number of the parent issue (number, required)
  • method: The action to perform on a single sub-issue Options are:
    • 'add' - add a sub-issue to a parent issue in a GitHub repository.
    • 'remove' - remove a sub-issue from a parent issue in a GitHub repository.
    • 'reprioritize' - change the order of sub-issues within a parent issue in a GitHub repository. Use either 'after_id' or 'before_id' to specify the new position. (string, required)
  • owner: Repository owner (string, required)
  • replace_parent: When true, replaces the sub-issue's current parent issue. Use with 'add' method only. (boolean, optional)
  • repo: Repository name (string, required)
  • sub_issue_id: The ID of the sub-issue to add. ID is not the same as issue number (number, required)

Labels

• get_label - Get a specific label from a repository.

  • Required OAuth Scopes: repo
  • name: Label name. (string, required)
  • owner: Repository owner (username or organization name) (string, required)
  • repo: Repository name (string, required)

• label_write - Write operations on repository labels.

  • Required OAuth Scopes: repo
  • color: Label color as 6-character hex code without '#' prefix (e.g., 'f29513'). Required for 'create', optional for 'update'. (string, optional)
  • description: Label description text. Optional for 'create' and 'update'. (string, optional)
  • method: Operation to perform: 'create', 'update', or 'delete' (string, required)
  • name: Label name - required for all operations (string, required)
  • new_name: New name for the label (used only with 'update' method to rename) (string, optional)
  • owner: Repository owner (username or organization name) (string, required)
  • repo: Repository name (string, required)

• list_label - List labels from a repository

  • Required OAuth Scopes: repo
  • owner: Repository owner (username or organization name) - required for all operations (string, required)
  • repo: Repository name - required for all operations (string, required)

Notifications

• dismiss_notification - Dismiss notification

  • Required OAuth Scopes: notifications
  • state: The new state of the notification (read/done) (string, required)
  • threadID: The ID of the notification thread (string, required)

• get_notification_details - Get notification details

  • Required OAuth Scopes: notifications
  • notificationID: The ID of the notification (string, required)

• list_notifications - List notifications

  • Required OAuth Scopes: notifications