README.md
Docker-friendly server to create and manage GitHub repositories and files.
GitHub MCP Server (Node + TypeScript)
Docker-friendly Model Context Protocol server that lets Codex create and manage GitHub repositories with a single personal access token (PAT).
Features
create_repository: create a repo under the authenticated user or a given org.upsert_file: create/update files with commit messages on a branch.create_branch: branch off any ref (defaults frommain).whoami: show the PAT identity.
Requirements
- Node 20+ (or Docker).
- GitHub PAT in
GITHUB_TOKENwith at leastreposcope (orpublic_repoif you only touch public repos). - For org repos, ensure the token can create repos in that org and that SSO/org policies allow it.
Local dev
npm install
npm run dev
Docker build and run
docker build -t github-mcp .
docker run -i --rm -e GITHUB_TOKEN=... github-mcp
Wire up to Codex (VS Code)
The server speaks MCP over stdio. Configure Codex to start it with:
{
"mcpServers": {
"github-mcp": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "github-mcp"]
}
}
}
[mcp_servers.github-mcp]
command = "docker"
args = ["run", "-i", "--rm", "--env-file", "pathToEnv", "github-mcp"]
Important: use "-e", "GITHUB_TOKEN" (without =${GITHUB_TOKEN}) when the command is launched directly (non-shell), so Docker forwards the host GITHUB_TOKEN value correctly.
Notes and safety
- The server uses your PAT directly; treat it like a password.
- Actions are direct commits; there is no local clone.
- If you need organization SAML, approve the PAT for that org first.
Extending
- Add tools via
server.tool(name, { description, inputSchema }, handler)insrc/index.ts.
Tools (4)
create_repositoryCreate a new repository under the authenticated user or a given organization.upsert_fileCreate or update files with commit messages on a specific branch.create_branchCreate a new branch off any reference.whoamiDisplay the identity associated with the current personal access token.Environment Variables
GITHUB_TOKENrequiredGitHub Personal Access Token with repo scope.Configuration
claude_desktop_config.json
{"mcpServers": {"github-mcp": {"command": "docker", "args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "github-mcp"]}}}Try it
→Create a new repository named 'my-new-project' under my account.
→Create a new file named 'README.md' in the 'main' branch with the content 'Hello World'.
→Create a new branch called 'feature-login' based on the 'main' branch.
→Check which GitHub account is currently authenticated.