MCP 서버 실전 예제: GitHub 이슈를 AI 에이전트에게 연결하기

MCP 서버 실전 예제: GitHub 이슈를 AI 에이전트에게 연결하기

2026. 5. 22. 17:29ㆍ카테고리 없음

최근 AI 코딩 도구들은 단순히 질문에 답하는 수준을 넘어 실제 개발 환경과 연결되는 방향으로 발전하고 있습니다. 파일을 읽고, 코드를 수정하고, 테스트를 실행하고, GitHub 이슈나 문서를 참고하면서 작업하는 식입니다.

이때 중요한 개념 중 하나가 MCP(Model Context Protocol) 입니다.

MCP는 AI 에이전트가 외부 도구나 데이터에 접근할 수 있도록 해주는 표준화된 연결 방식입니다. 쉽게 말하면 AI에게 “이 도구를 이런 방식으로 사용할 수 있다”고 알려주는 인터페이스입니다.

이전 글에서 MCP가 무엇인지 개념을 살펴봤다면, 이번 글에서는 조금 더 실전적인 예제로 들어가보겠습니다. 목표는 간단합니다.

AI 에이전트가 GitHub 저장소의 이슈 목록을 조회할 수 있도록 MCP 서버를 만들어본다.

왜 필요한가

개발 업무에서 GitHub 이슈는 중요한 문맥입니다.

지금 어떤 버그가 열려 있는가?
어떤 기능 요청이 논의 중인가?
특정 PR이나 커밋이 어떤 이슈와 연결되어 있는가?
에이전트에게 맡길 만한 작업은 무엇인가?

사람 개발자는 GitHub 화면을 열고 이슈를 확인한 뒤 작업합니다. 하지만 AI 에이전트가 같은 일을 하려면 GitHub에 접근할 수 있는 도구가 필요합니다.

물론 에이전트에게 GitHub CLI를 직접 실행하게 할 수도 있습니다. 하지만 MCP 서버로 감싸면 다음과 같은 장점이 있습니다.

1. AI에게 필요한 기능만 노출할 수 있다

GitHub API 전체를 AI에게 열어주는 대신, 예를 들어 list_issues, get_issue, search_issues 같은 필요한 기능만 제공할 수 있습니다.

2. 입력과 출력 형식을 명확히 할 수 있다

AI가 사용할 도구의 파라미터와 응답 구조를 미리 정의할 수 있습니다. 그러면 에이전트가 더 안정적으로 도구를 호출합니다.

3. 사내 API나 내부 도구로 확장하기 쉽다

GitHub 이슈 조회 예제를 이해하면 나중에는 Jira, Linear, Notion, 사내 관리자 API, 배포 시스템 등으로 확장할 수 있습니다.

핵심 개념

MCP 서버는 AI 에이전트에게 사용할 수 있는 도구 목록을 제공합니다. 도구 하나는 대략 다음 요소를 가집니다.

이름
설명
입력 스키마
실행 로직
응답 데이터

예를 들어 GitHub 이슈를 조회하는 도구라면 다음과 같이 정의할 수 있습니다.

도구 이름: list_github_issues
설명: 특정 GitHub 저장소의 열린 이슈 목록을 조회한다.
입력값: owner, repo, state, limit
응답값: issue number, title, url, labels, created_at

AI 에이전트는 이 설명을 보고 필요할 때 도구를 호출합니다.

실무 적용 방법

이번 예제는 Node.js 기반으로 구성해보겠습니다. 실제 프로젝트에서는 TypeScript를 사용하는 것을 추천하지만, 흐름을 이해하기 위해 구조 위주로 설명하겠습니다.

1. 프로젝트 생성

먼저 MCP 서버용 프로젝트를 하나 만듭니다.

mkdir github-issues-mcp
cd github-issues-mcp
npm init -y

필요한 패키지를 설치합니다.

npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

package.json에는 실행 스크립트를 추가합니다.

{
  "scripts": {
    "dev": "tsx src/server.ts"
  }
}

2. GitHub 토큰 준비

GitHub API를 호출하려면 토큰이 필요합니다. 공개 저장소의 공개 이슈만 조회한다면 토큰 없이도 가능하지만, API 제한이나 private 저장소 접근을 고려하면 토큰을 사용하는 편이 좋습니다.

환경 변수로 관리합니다.

export GITHUB_TOKEN=ghp_xxx

실제 운영에서는 .env 파일이나 비밀 관리 도구를 사용하는 것이 좋습니다. 중요한 점은 토큰을 코드에 직접 넣지 않는 것입니다.

3. GitHub 이슈 조회 함수 만들기

먼저 GitHub REST API를 호출하는 함수를 작성합니다.

// src/github.ts
export async function listIssues(params: {
  owner: string
  repo: string
  state?: "open" | "closed" | "all"
  limit?: number
}) {
  const { owner, repo, state = "open", limit = 10 } = params
  const token = process.env.GITHUB_TOKEN

  const url = new URL(`https://api.github.com/repos/${owner}/${repo}/issues`)
  url.searchParams.set("state", state)
  url.searchParams.set("per_page", String(limit))

  const response = await fetch(url, {
    headers: {
      Accept: "application/vnd.github+json",
      ...(token ? { Authorization: `Bearer ${token}` } : {}),
    },
  })

  if (!response.ok) {
    throw new Error(`GitHub API error: ${response.status} ${response.statusText}`)
  }

  const issues = await response.json()

  return issues
    .filter((issue: any) => !issue.pull_request)
    .map((issue: any) => ({
      number: issue.number,
      title: issue.title,
      url: issue.html_url,
      state: issue.state,
      labels: issue.labels.map((label: any) => label.name),
      created_at: issue.created_at,
    }))
}

여기서 pull_request가 있는 항목을 제외하는 이유는 GitHub API에서 issues endpoint가 PR도 함께 반환하기 때문입니다.

4. MCP 서버 만들기

이제 MCP 서버를 작성합니다.

// src/server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
import { z } from "zod"
import { listIssues } from "./github"

const server = new McpServer({
  name: "github-issues-mcp",
  version: "1.0.0",
})

server.tool(
  "list_github_issues",
  "특정 GitHub 저장소의 이슈 목록을 조회합니다.",
  {
    owner: z.string().describe("GitHub owner 또는 organization 이름"),
    repo: z.string().describe("GitHub repository 이름"),
    state: z.enum(["open", "closed", "all"]).default("open"),
    limit: z.number().min(1).max(30).default(10),
  },
  async ({ owner, repo, state, limit }) => {
    const issues = await listIssues({ owner, repo, state, limit })

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(issues, null, 2),
        },
      ],
    }
  }
)

const transport = new StdioServerTransport()
await server.connect(transport)

이 서버는 표준 입출력(stdio)을 통해 MCP 클라이언트와 통신합니다. Claude Desktop, Cursor, Hermes 같은 MCP 클라이언트는 이 서버를 실행하고 도구 목록을 읽어 사용할 수 있습니다.

AI 에이전트에 연결하기

MCP 클라이언트 설정은 도구마다 조금씩 다르지만, 기본적으로는 다음 정보를 등록합니다.

서버 이름
실행 명령어
실행 인자
환경 변수

예를 들면 다음과 같은 형태입니다.

{
  "mcpServers": {
    "github-issues": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/github-issues-mcp",
      "env": {
        "GITHUB_TOKEN": "..."
      }
    }
  }
}

실제 설정 파일 위치나 형식은 사용하는 AI 도구에 따라 다릅니다. 중요한 것은 AI 에이전트가 이 MCP 서버를 실행할 수 있고, list_github_issues 도구를 발견할 수 있어야 한다는 점입니다.

사용 예시

연결이 완료되면 AI에게 이런 식으로 요청할 수 있습니다.

mishka86/example-repo 저장소의 열린 이슈를 조회하고,
프론트엔드 개발자가 먼저 처리하면 좋을 작업 3개를 골라줘.

그러면 AI는 MCP 도구를 호출해 이슈 목록을 가져온 뒤, 제목과 라벨을 보고 우선순위를 제안할 수 있습니다.

또는 다음처럼 사용할 수도 있습니다.

최근 열린 버그 이슈를 확인하고,
각 이슈를 재현하기 위해 필요한 정보를 정리해줘.

이런 흐름이 가능해지면 AI 에이전트는 단순히 코드만 생성하는 도구가 아니라, 프로젝트 관리 문맥까지 참고하는 작업 파트너가 됩니다.

에러 처리 고려사항

실무에서 MCP 서버를 만들 때는 에러 처리가 중요합니다.

GitHub API 제한

토큰 없이 호출하면 rate limit에 빨리 걸릴 수 있습니다. 가능하면 토큰을 사용하는 것이 좋습니다.

권한 문제

private repository에 접근하려면 토큰에 적절한 권한이 있어야 합니다. 권한이 부족하면 404처럼 보이는 응답이 올 수도 있습니다.

입력값 검증

MCP 도구의 입력값은 zod 같은 스키마로 검증하는 것이 좋습니다. AI가 잘못된 파라미터를 넘기더라도 서버가 명확한 에러를 반환할 수 있어야 합니다.

응답 크기 제한

이슈가 너무 많으면 응답이 커질 수 있습니다. limit을 두고 필요한 필드만 반환하는 것이 좋습니다.

확장 아이디어

이 예제는 단순히 이슈 목록을 조회하는 수준이지만, 다음과 같이 확장할 수 있습니다.

1. 특정 이슈 상세 조회

get_github_issue(owner, repo, issue_number)

본문, 댓글, 라벨, assignee를 함께 가져올 수 있습니다.

2. 라벨 기준 검색

search_github_issues(owner, repo, labels, state)

bug, good first issue, frontend, priority-high 같은 라벨 기준으로 필터링할 수 있습니다.

3. 이슈 요약

MCP 서버는 데이터를 가져오고, 요약은 AI가 담당하게 할 수 있습니다. 역할을 나누면 서버는 단순하고 안정적으로 유지됩니다.

4. Linear나 Jira로 확장

GitHub 이슈 대신 Linear, Jira, Notion 데이터베이스도 같은 방식으로 연결할 수 있습니다. 핵심은 외부 API를 MCP 도구 형태로 감싸는 것입니다.

주의할 점

MCP 서버를 만들 때 AI에게 너무 많은 권한을 주지 않는 것이 좋습니다.

처음에는 읽기 전용 도구부터 시작하는 것을 추천합니다.

이슈 목록 조회
이슈 상세 조회
댓글 조회
라벨 조회

이후 충분히 안정화되면 쓰기 기능을 추가할 수 있습니다.

이슈 생성
댓글 작성
라벨 변경
담당자 지정

하지만 쓰기 기능은 실수했을 때 실제 프로젝트에 영향을 줄 수 있으므로 승인 절차를 두는 것이 안전합니다.

정리

MCP는 AI 에이전트가 외부 시스템과 안전하고 일관된 방식으로 연결될 수 있게 해주는 중요한 프로토콜입니다.

이번 글에서는 GitHub 이슈를 조회하는 간단한 MCP 서버 예제를 살펴봤습니다. 핵심 흐름은 다음과 같습니다.

GitHub API를 호출하는 함수를 만든다.
MCP 서버를 생성한다.
list_github_issues 도구를 정의한다.
AI 에이전트에 MCP 서버를 등록한다.
에이전트가 이슈 목록을 조회하고 작업 문맥으로 활용한다.

AI 코딩 에이전트를 제대로 활용하려면 단순히 좋은 프롬프트를 작성하는 것만으로는 부족합니다. 프로젝트의 실제 문맥, 이슈, 문서, 배포 상태, 내부 API를 AI가 읽을 수 있어야 합니다.

MCP는 그 연결 지점을 표준화해주는 도구입니다. 작은 읽기 전용 MCP 서버부터 만들어보면, AI 에이전트를 실무 환경에 어떻게 안전하게 연결할 수 있을지 감을 잡을 수 있습니다.

저작자표시 (새창열림)

Mishka's 블로그