
How to Set Up the Official GitHub MCP Server for AI Coding Agents on Linux: Docker, Token Scopes, and Security Guardrails
Set up GitHub MCP with a deliberately limited trust boundary
The official GitHub MCP server lets an AI coding assistant request GitHub repository information through Model Context Protocol tools. If a coding agent can read untrusted issue text or pull-request content, it must not be able to turn that text into permission to execute a shell command or reveal credentials.
Reviewed November 13, 2026. This guide distinguishes a read-only server tool filter, a repository-scoped GitHub credential, and host-level permission boundaries. They protect different resources. It does not claim that enabling one option makes all agent actions safe.
The definitive upstream implementation and configuration references are the GitHub MCP server repository and official server-configuration documentation.
1. Choose your client and authentication route
Start with the actual MCP client (for example, a supported IDE or agent environment), its current GitHub connection workflow, and its credential storage model. The upstream server repository documents options for authentication, including host-supported OAuth flows and personal access tokens; whether a particular IDE offers each workflow varies with that client version.
Prefer a supported, user-authorized OAuth connection when available and appropriate for the client. For a PAT-based local deployment, arrange for the token to be supplied by the host’s approved secret mechanism, not pasted into a tracked JSON file, command-line argument, model prompt or chat transcript.
The GitHub PAT documentation distinguishes classic and fine-grained personal access tokens. GitHub recommends using fine-grained tokens when possible and describes their repository selection and permission constraints.
Before connecting: identify exactly which repositories and operations the agent actually needs. Reading repository contents, inspecting issues, posting review comments and creating pull requests require different permissions. Do not grant write access merely because the client supports write tools.
2. Restrict the GitHub credential itself
For a PAT used by a small review-only agent, the intended policy is:
| Choice | Review-first recommendation | What still needs checking |
|---|---|---|
| Repository selection | Only repositories needed for the task | Effective token permissions and organization policy |
| Contents and pull requests | Read access when only inspection is needed | Whether actual tools require additional permissions |
| Issues and discussions | Read access only for triage | Whether untrusted text enters prompts |
| Administration | No access unless explicitly needed | Whether any other credential grants it |
| Expiration and rotation | Set according to organization policy | Safe storage, revocation and incident response |
This is a principle of least privilege, not a universal permission matrix: permissions must be chosen using the currently documented GitHub API requirements for the tools you intend to enable. Never present a copied PAT-shaped string as a working secret.
The server must use a token through the calling host’s actual supported secret handling. Do not assume every IDE expands an environment-variable placeholder in configuration JSON or keeps secrets encrypted just because another client does.
3. Apply GitHub MCP’s tool filters separately from the token
The upstream GitHub MCP server configuration documents local server settings including the GITHUB_READ_ONLY environment variable and GITHUB_TOOLSETS selection. Read-only mode filters write-capable tools in the GitHub MCP server; choosing toolsets limits which server capabilities are offered.
A configuration checklist, not an executable Docker command or a validated host-specific file, is:
| Layer | Setting to confirm | Failure mode if assumed instead of verified |
|---|---|---|
| MCP server image | Official source and reviewed, pinned release or immutable digest | An unpinned image changes under a previously written tutorial |
| Container auth | GITHUB_PERSONAL_ACCESS_TOKEN supplied through approved host secret handling | A literal token in a config file or process argument may leak |
| GitHub MCP read-only mode | GITHUB_READ_ONLY, using the documented setting for the pinned server version | A client setup may omit the option, leaving write tools enabled |
| GitHub MCP tool visibility | GITHUB_TOOLSETS set to a documented minimal subset | Unexpected capabilities can appear in the tool list |
| GitHub API permissions | Repository-scoped, least-privilege token | Server-level filtering does not remove the underlying token privileges |
| Agent-wide tools | Separately review any shell, filesystem, browser and other GitHub tools | A read-only GitHub MCP server does not control every tool in the agent |
Important: GITHUB_READ_ONLY is a GitHub MCP application option, not the Docker engine’s --read-only filesystem option. Likewise, restricting MCP tool lists does not guarantee that another agent connector cannot modify files or repositories. Inspect the actual tool list and the host application’s other enabled actions.
The official configuration page is versioned by its live repository branch. Pin the actual image/version and verify both the advertised flags and tool names in that release before attempting a deployment.
4. Confirm the container and STDIO boundary without leaking tokens
The official GitHub MCP repository documents a local containerized deployment and standard input/output integration options. A correct MCP session requires the host client, the server process and credentials to agree on the selected method. A server process starting is not enough to prove the tool’s access policy or GitHub API permissions.
For a local environment you own and are authorized to configure, use this non-executable acceptance checklist:
- Record the pinned container digest, GitHub MCP server version and MCP client version.
- Confirm the token is not printed in logs, chat prompts, process arguments or committed files.
- Verify the actual server configuration is set to read-only, then inspect advertised tools for unintended write operations.
- Test one authorized repository-read operation using a disposable, non-sensitive repository.
- Attempt a representative write operation only in a controlled negative test and confirm it is blocked by the intended policy.
- Validate that expiration or revocation of the credential causes the expected failure without leaking the credential or silently falling back to a broader one.
Do not copy a generic CLI command that puts the token directly in the docker run argument or configuration text. Do not assume a token is isolated inside the container: the host must supply it somehow, and host-side logs, environment exposure and tool permissions remain relevant.
5. Treat GitHub issue content as untrusted tool output
Issues, pull-request descriptions, code comments and repository files can contain adversarial instructions. They should be treated as data to analyze, not as instructions that override the human’s task or the agent’s tool authorization.
An XML wrapper, HTML escaping, a prompt phrase such as “ignore untrusted instructions”, or the server’s read-only mode does not independently make an entire agent safe. In particular, a GitHub MCP read-only setting cannot restrain a separately enabled shell tool, another GitHub connector, or credentials held elsewhere by the client.
For any task with side effects, require an explicit authorization path and independent policy checks; keep untrusted tool-return content separate from commands. Design a negative test using a harmless, synthetic instruction inserted into a test issue, and verify no unintended action occurs.
The MCP specification’s HTTP authorization section is relevant if using an HTTP transport. Do not apply HTTP-specific OAuth assumptions unmodified to a local STDIO child process.
6. Avoid escalating Docker host privileges as a quick fix
A Docker socket permission error is not a reason to add an untrusted agent user to the Docker group automatically. The official Docker Engine security reference explains that control of the Docker daemon is a sensitive host-level privilege, especially on a standard rootful daemon.
Have the host administrator choose an approved deployment method, dedicated execution environment or rootless configuration where suitable. Avoid broad privileged container flags, host network/IPC sharing or exposing a local MCP service to an untrusted network just to make an example start.
7. What qualifies as success
Only call the setup successful when it is verified on your chosen versions: a trusted client connects, the credential reaches only authorized repositories, the MCP server’s discovered tool list excludes unexpected write tools, and a controlled unauthorized operation is rejected. Record the tool list and redacted outcomes; do not publish the credential, full environment or private repository contents.
Verification limits: This article was checked against current first-party documentation. It does not claim a production GitHub login, live Docker container run, fine-grained token provisioning, IDE integration or cross-tool safety experiment was executed by the publisher. The published instructions are an auditable deployment checklist, not a universally working copy-and-run configuration.
Official primary references
- GitHub MCP server repository and official local integration
- GitHub MCP server configuration and read-only/toolset settings
- GitHub fine-grained and classic PAT guidance
- Docker daemon security model
- MCP HTTP transport authorization specification
Source-reviewed November 13, 2026. Original publication metadata and URL preserved.