github-mcp-server

A Model Context Protocol server that exposes one GitHub repository as agent tools, built with Java 21 + Spring Boot + Spring AI.

Deliberately scoped: the agent can only touch the single repository the server was configured for — branching, committing files and opening pull requests. No repo administration, no deletes.

Part of a three-repo agentic workflow:

Repo	Role
trello-mcp-server	MCP tools over a Trello board
github-mcp-server (this)	MCP tools over one GitHub repository
ticket-coder-agent	LangChain4j agent that turns Trello tickets into GitHub pull requests

Tools

Tool	Description
getRepositoryInfo	Full name, default branch, url
createBranch(branchName)	New branch from the default branch head
getFileContent(branch, path)	Read a file
createOrUpdateFile(branch, path, content, commitMessage)	Commit a file (handles create vs update automatically)
openPullRequest(branchName, title, body)	PR into the default branch; returns the PR url

Configuration (environment variables)

Variable	Meaning
GITHUB_TOKEN	Fine-grained PAT with Contents: read/write and Pull requests: read/write on the target repo
GITHUB_OWNER	Repository owner
GITHUB_REPO	Repository name
GITHUB_API_BASE_URL	Optional; defaults to https://api.github.com (point it at a mock for offline testing)

Run

mvn package
java -jar target/github-mcp-server-0.1.0.jar

The server speaks MCP over stdio: stdout carries only JSON-RPC, all logging goes to logs/github-mcp-server.log (see logback-spring.xml).

Tests

mvn test

Unit tests stub the GitHub REST API with MockRestServiceServer — no network or token needed. GITHUB_API_BASE_URL also makes full end-to-end testing possible against a local emulator.