stateful-auth-for-the-github

The GitHub MCP Server bridges AI tools directly to GitHub, enabling natural language queries and multi-step workflows over repositories, issues, PRs, workflows, and code. Once the server is running, you can connect your MCP host to the remote GitHub MCP Server and start issuing prompts that leverage GitHub context. Typical capabilities include reading repository structure and file contents, analyzing code, querying issues and PRs, monitoring Actions workflow runs, and automating common tasks like triaging issues or creating and updating PRs. The server is designed to support AI agents and chatbots that need authoritative access to GitHub data through a secure, token-authenticated remote service. To use it, provide a GitHub Personal Access Token (PAT) with the permissions you’re comfortable granting, set it as an environment variable for the container, and rely on the host’s MCP configuration to connect and proxy requests to GitHub.

Tools and capabilities available include: repository browsing and code search, code analysis and security findings review, workflow and Actions monitoring, issue/PR creation and updates, and automation of routine GitHub tasks. The remote server approach allows you to run the MCP server in a container with your PAT, enabling access without embedding credentials in client tooling. When connected, AI tools can perform complex multi-step tasks by composing prompts that leverage GitHub’s data and actions capabilities directly through the MCP bridge.

Prerequisites:

• Docker installed and running on your host
• A GitHub Personal Access Token (PAT) with the permissions you want to grant the AI tools
• Optional: access to ghcr.io to pull the ghcr.io/github/github-mcp-server image

Step 1: Prepare your GitHub PAT

• Create a PAT at https://github.com/settings/personal-access-tokens/new
• Ensure it has the scopes required for the actions you intend to automate (read repository content, read/write issues/PRs, workflow access, etc.)

Step 2: Run the MCP server in Docker

• Ensure Docker is running
• Run the following command, replacing your_token with your PAT or wiring it via your MCP host inputs:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=your_token \
  ghcr.io/github/github-mcp-server

Step 3: Connect your MCP host to the remote server

• In your MCP host configuration, point to the remote server as appropriate for your environment (VS Code remote MCP, or other hosts) and supply the PAT when prompted or via inputs.
• If your host supports environment token injection, set the GITHUB_PERSONAL_ACCESS_TOKEN environment variable accordingly.

Step 4: Validate the connection

• Use a simple prompt or test command in your MCP host to confirm that the server can access GitHub data (e.g., list repository contents or read a file). Troubleshoot by ensuring the PAT has the correct scopes and that Docker can access the network.

Tips and common issues:

• Ensure the PAT has the minimum required scopes for the tasks you plan to automate. Rotating PATs will require updating the environment variable on the host.
• If you encounter image pull issues from ghcr.io, you may need to: docker logout ghcr.io and re-authenticate, or ensure you have network access and valid credentials.
• The MCP host should manage token exposure securely. Avoid printing tokens in logs; prefer secure prompt inputs or secret management features of your host.
• When using remote servers, be mindful of rate limits and token scopes; adjust permissions according to the principle of least privilege.
• If your host supports multiple servers, you can run multiple MCP servers in parallel with distinct tokens or scopes.