Last updated 13 October 2026
Connect GitHub MCP server to Claude Code
The gap between your terminal and GitHub
You spend your day switching between the terminal where you write code and the browser where you manage tickets. When you use Claude Code, the agent knows your local files through the Read and Glob tools, but it is blind to the context living in your GitHub issues and pull requests. You have to copy and paste issue descriptions manually, which breaks the flow of a terminal-first workflow. Bridging this gap requires the Model Context Protocol to give the agent a direct line to the GitHub API. This allows the agent to pull in information that is not currently on your hard drive but is essential for the task at hand.
Connecting a GitHub MCP server allows the agent to perform actions like listing open issues, reading comments, and creating new repositories. This transforms the agent from a local file editor into a collaborator that understands the broader project management layer. You no longer need to explain the requirements of a feature if they already exist in a GitHub issue. The agent can fetch that data itself and start proposing edits based on the actual ticket description. This integration reduces the cognitive load of manual context switching and ensures that the code the agent produces aligns with the official project requirements tracked online.
Creating a GitHub personal access token
The GitHub MCP server requires an authenticated connection to talk to your account. You must generate a personal access token with the classic scope or fine-grained permissions. At a minimum, the token needs access to repository metadata, issues, and pull requests. If you plan to let the agent create repositories or push changes directly through the API, ensure those scopes are selected during the token creation process on GitHub. You should treat this token like a password. If it is leaked, anyone can access your repositories with the permissions you granted.
Store this token securely on your machine. You will need to provide it during the configuration phase. It is common practice to set this as an environment variable in your shell profile, such as your zshrc or bashrc file. The MCP server will look for this specific variable when it attempts to initialize the connection. Without a valid token, the server will fail to start and the agent will not show any GitHub-related tools in the tool list. If you are using a professional account, check if your organization has restrictions on personal access tokens before you begin.
Configuring the server through the command line
The primary way to add a new server is through the claude mcp command. When you run this, the interface guides you through adding a new configuration. You will need to provide the name of the server and the command used to run it. For the GitHub MCP server, this usually involves a command that initiates a node process or a pre-compiled binary. You must also pass the GitHub token as an environment variable within this configuration setup. This step links the command line agent to the external GitHub service.
This process modifies the .mcp.json file in your project or the global configuration. If you want the GitHub tools to be available everywhere, configure them at the user level. If the tools should only work for a specific repository, place the configuration in that repo root. Once added, the agent detects the new capabilities automatically. You can verify the status of your connected servers at any time by typing /mcp inside an active session. This will list all active servers and show whether the GitHub connection is live and ready to receive requests.
Managing multiple repositories with adhdTerminal
When you work across five different microservices, keeping track of five different Claude Code sessions in a single terminal window becomes a burden. You might have one session focused on a GitHub issue in the backend repo and another session refactoring a shared library. Switching between these requires constant directory changes and session resumes. This is where adhdTerminal provides a visual solution for your workflow. It is a native app for macOS and Windows that runs many Claude Code sessions side by side.
The adhdTerminal app lets you run these sessions as tiles on a wall. Each tile can represent a different repository with its own GitHub MCP connection. You can see at a glance which session is working, waiting for you, or idle. Since tiles resume their exact state and position after a restart, you do not lose the context of your conversation or the specific GitHub issue you were working on. This is especially helpful when you are waiting for a long-running GitHub task to finish in one repo while you start a new task in another.
Using GitHub tools in an active session
After the server is configured, you start a session by typing claude in your repository. To see if the GitHub tools are active, use the /help command or simply ask the agent what tools it has available. It should list tools for searching issues and reading repository content alongside the standard Bash and Read tools. You can now give a prompt like Read issue number forty two and implement the requested changes to the agent. It will use the GitHub tools to fetch the text of that issue directly from the API.
The agent will use the WebFetch or specialized GitHub tools to retrieve the issue body. It then uses the Glob and Grep tools to find the relevant files in your local project. This integration means the agent can cross-reference the remote ticket with your local code. If you are working on a bug fix, the agent can even search for similar issues in the repository history to see how previous developers solved comparable problems. This deep level of context allows the agent to make more informed decisions about where a bug might be hiding.
Controlling permissions and tool usage
Claude Code operates with specific permission modes that determine how much freedom the GitHub tools have. In the default mode, the agent asks for your approval before performing sensitive actions. If the GitHub MCP server attempts to create a new repository or delete a branch, the terminal will prompt you to allow or deny the action. You can cycle through these modes using Shift+Tab to switch between plan mode or acceptEdits mode. This gives you the flexibility to let the agent work autonomously or keep it on a tight leash.
You can fine-tune these permissions in the settings.json file inside the .claude directory. By editing the permissions section, you can set specific GitHub tools to be always allowed or always denied. For example, you might want to allow the tool that reads issues without a prompt, but require a manual check for any tool that writes data back to the GitHub API. This ensures you maintain control over your remote data while still benefiting from the agent speed. Managing these settings helps prevent accidental pushes or deletions in your remote repositories.
Optimizing context window and session costs
Interacting with GitHub can quickly fill up your session context window. Every issue description, comment thread, and file content the agent reads adds to the total tokens used. You can monitor your current spend with the /cost or /usage commands. If the session becomes too long and the agent starts to lose track of the original goal, use the /compact command. This summarizes the conversation so far and clears out the older, detailed logs to make room for new data. It is a necessary maintenance step for long-running engineering tasks.
The /clear command is also useful if you want to switch to a completely different GitHub task without leaving the folder. It resets the conversation history but keeps the MCP server connections active. If you find yourself hitting token limits frequently, consider being more specific in your prompts. Instead of asking the agent to read all issues, ask it to fetch a specific issue ID to keep the injected context as small as possible. This disciplined approach to context management keeps your costs down and the agent performance high.
Troubleshooting connection and installation issues
If the GitHub tools do not appear, the first step is to run claude doctor from your shell. This command performs a health check on your installation and identifies any configuration errors in your settings files. If the doctor command reports that everything is fine but the tools are still missing, use the /doctor command inside a session. This provides a more specific look at the internal state of the current environment. You can also use adhdTerminal to quickly open a new test tile to see if the issue persists in a fresh session.
Connection errors often stem from an expired GitHub token or incorrect permissions in the .mcp.json file. Ensure that the command path to the MCP server is correct and that the node environment is accessible from the terminal where you run Claude Code. If you have recently updated the tool, run claude update to ensure you are on the latest version, as the MCP implementation frequently receives improvements for stability and performance. Checking the logs of the MCP server can also reveal if the GitHub API is rejecting your requests due to rate limiting.
Persistent instructions and subagents
You can guide how the agent interacts with GitHub by adding instructions to your CLAUDE.md file. For instance, you can specify that the agent should always check for open pull requests before starting a new feature. These instructions sit at the root of your repo and are read by the agent at the start of every session. This ensures that the GitHub MCP server is used according to your team's specific workflow and coding standards. It acts as a permanent memory for the project that every agent session respects.
For complex GitHub tasks, you can also define custom subagents in the .claude/agents directory. A subagent can be specialized for triage, where its only job is to read new GitHub issues and label them. By creating these markdown-based agent definitions, you can modularize your workflow. Instead of one agent trying to do everything, you can invoke a subagent that has a focused prompt and a specific set of GitHub-related instructions. This keeps the main agent free to focus on coding while the subagent handles the administrative work.
Questions people ask
How do I update the GitHub token if it expires?
You can update the token by running claude mcp again and selecting the option to edit the existing GitHub server. Alternatively, you can open your .mcp.json file or your shell profile and replace the old token string with the new one. After saving the file, restart your session for the changes to take effect.
Can I use the GitHub MCP server to create pull requests?
Yes, if the GitHub MCP server you installed supports that specific tool and your token has the correct permissions. You can ask the agent to create a pull request after it finishes a task. The agent will then use the provided tool to communicate with the GitHub API and submit your local branch for review.
What should I do if the GitHub API rate limit is reached?
If you hit a rate limit, the agent will receive an error from the MCP server. You should use the /compact command to reduce the number of requests the agent makes in future turns. If the problem persists, you may need to wait for the limit to reset or use a token with higher limits.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.