slim-github-mcp

읽기 전용 GitHub MCP 서버로, 작은 결과를 반환합니다.

대부분의 GitHub MCP 서버는 모델에 GitHub API의 원시 객체를 훔켜. 전달합니다. 빠른 API 뒤에 있는 프론트엔드 모델(Frontier model)에게는 괜찮지만 로컬 모델에는 고통입니다. 저장소 검색 결과의 한 페이지는 약 **14KB JSON(≈3.5k 토큰)**입니다. 그 대부분이, 아무도 읽지 않을 URL과 권한 플래그죠. 게다가 도구 스키마의 ~7k 토큰이 더해지면, 로컬에서 호스팅되는 모델은 "내 저장소 목록"을 처리할 때 몇 분가 걸리거나 아예 끝내지 못할 수도 있습니다.

이 서버는 정반대의 입장을 취합니다. 모든 도구는 몇 가지 유용한 필드만을 반환하고, 모든 목록은 서버 측에서 상한을 가지며, 전체 도구의 수는 아홉 개입니다. 모델이 어떤 아규먼트를 만들어도 커다란 페이로드를 가져올 수 없습니다.

도구

모든 limit은 기본값 10이며, 최대 30으로 제한됩니다. gh_file은 20k자에서 잘라내고, truncated 플래그를 반환합니다. 저장소에 대한 반환 정보는 full_name, private, 160자 길이 description, language, stars, updated, url뿐 입니다 — 그 외에는 없습니다.

의도적인 심 write 경로는 없습니다. 클라이언트는 api.github.com에 대해서는 GET만 발생합니다.

Related MCP server: GitHub MCP Server

GitHub 토큰 가져오기

서버에는 모든 호출에 사용하는 토큰 하나면 충분힙니다. 읽기에 대한 권한만 필요합니다.

1. GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token로 이동합니다.

2. 만료일을 설정하고 토큰이 볼 수 있는 저장소를 선택하세요 — Public repositories only인 경우 비공개 데이터가 GitHub 밖으로 나가지 않 지정하는 것이며, gh_my_repos(visibility="private")를 사용하고 싶다면 All repositories를 선택하세요.

3. Repository permissions에서 실제로 필요한 것만 자유 읽기 전용 권한을 부여하세요:

   • Metadata: Read-only — 필수. 저장소 나열 및 검색에 충분

   • Contents: Read-only — gh_file 및 gh_commits용

   • Issues: Read-only — gh_issues용

   • Pull requests: Read-only — gh_pulls용

4. 모든 Account permission은 손대지마세요.

5. 토큰을 복사하세요 — GitHub은 한 번만 보여줍니다.

repo 범위를 가진 classic 토큰도 동작하지만, 이 서버가 필요한 것보다 훨씬 광범위하니, fine-grained 토큰이 좋습니다.

인증되지 않은 GitHub API 요청은 시간당 60회 제한이므로, 실제로는 토큰이 필요합니다. 인증된 테 스코어를으로 할 시에는 시간당 5,000회 호출됩니다.

설치

git clone https://github.com/0xBakeer/slim-github-mcp.git
cd slim-github-mcp

python3 -m venv venv
./venv/bin/pip install -r requirements.txt

cp .env.example .env
$EDITOR .env            # put your token in GITHUB_MCP_TOKEN

실행합니다:

set -a; . ./.env; set +a
./venv/bin/uvicorn slim_github_mcp.main:app --host 127.0.0.1 --port "${GITHUB_MCP_PORT:-9130}"

정상적으로 올라오는지, 토큰이 동작하는지 확인합니다:

curl -s http://127.0.0.1:9130/api/health
curl -s -H "Authorization: Bearer $GITHUB_MCP_SECRET" \
     'http://127.0.0.1:9130/api/my-repos?visibility=public&limit=5'

MCP 엔드포인트 자체는:

http://127.0.0.1:9130/tools/mcp/v1

이 확장은 스트리밍 HTTP를 지원하므로, URL을 받는 모든 MCP 클라이언트에서 이용 가능합니다.

구성

포트가 localhost 이외의 것에 노출될 수 있을 때는 GITHUB_MCP_SECRET을 설정하세요. 이 서버는 사용자가 보유한 비공개 저장소를 읽을 수 있는 토큰을 들고 있고, 다른 방법으로는 호출자를 인증하지 않습니다. openssl rand -hex 24로 시크릿을 생성하세요.

GITHUB_MCP_PUBLIC_HOST가 필요한 이유는, MCP가 기본적으로 DNS 리바인딩 보호를 사용하기 때문입니다. 리버스 프록시로 도착하는 요청은 실제 퍼블릭 Host헤더를 가지며, 해당 호스트 정보가 선언되지 않으면 거부됩니다. 설정을 잊은 경우/api/health는 정상인데 MCP 엔드포인트에서 400`이 나타납니다.

서비스로 실행하기

scripts/github-mcp.service는 수정해 사용할 수 있는 systemd 유닛입니다. User, 경로를 설정하고, 위의 변수들이 담긴 루트 소유 0600 파일을 가리키는 EnvironmentFile을 지정하세요. 유닛 파일에 토큰을 넣지 마세요.

또한 Dockerfile도 있습니다:

docker build -t slim-github-mcp .
docker run -d --name github-mcp -p 127.0.0.1:9130:9130 --env-file .env slim-github-mcp

리버스 프록시 뒤에 배치

특별한 점은 없지만, MCP는 스트리밍 방식이라 버퍼를 꺼야 합니다:

location /tools/mcp/ {
    proxy_pass http://127.0.0.1:9130;
    proxy_set_header Host $host;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600s;
}

GITHUB_MCP_PUBLIC_HOST에 프록시에 사용하는 호스트명을 설정하세요.

Open WebUI와 함께 사용하기

Open WebUI는 MCP를 기본적으로 지원합니다 (0.6.x 이상). 헬퍼 스크립트로 서버를 등록합니다:

export OPEN_WEBUI_URL=https://webui.example.com
export OPEN_WEBUI_KEY=sk-...                      # Settings -> Account -> API keys
export GITHUB_MCP_URL=http://127.0.0.1:9130/tools/mcp/v1
export GITHUB_MCP_SECRET=...                      # if you set one

./scripts/register-open-webui.sh

이 방법은 엔트리를 Open WebUI의 기존 도구 서버들에 병합 확장하며 (id로 매칭되므로 다시 실행하면 업데이트만 수행), 그리고 발견된 도구를 출력합니다:

==> Verifying tool discovery
    9 tools: gh_whoami, gh_my_repos, gh_user_repos, ...

수동으로 하고 싶다면: Admin Settings → Tools → Add Tool Server, MCP 유형 선택, URL은 위와 같이, Bearer 인증으로 시크릿을 넣으면 됩니다.

자주 놓치는 두 가지:

• 채팅의 도구 선택 픽커에서 도구를 활성화하세요. 등록된 서버가 자동으로 모델에 제공되진 않습니다.

• 모델별로 도구를 고정 경우 (Workspace → Models → Tools) 거기에도 추가하세요. Open WebUI는 이것을 server:mcp:<id>로 저장합니다. 서버 id를 나중에 고정하면 이 참조는 사라지고, 모델은 여전히 응답하지만 도구 없이 추측만으로 답변하게 됩니다.

알아두면 좋을 사항: tool_ids를 지정하여 /api/chat/completions를 직접 호출하면 도구 서버가 연결이 되지 않습니다. 도구 연결은 프론트엔드에서 일어나므로, UI로 테스트해야 합니다.

라이센스

MIT