AIMIZING
블로그 목록으로 돌아가기

로컬 환경에서 AI 에이전트 구축하기: gpt-oss-20b, Ollama, MCP 통합 가이드

2025-09-01
MCP
#gpt-oss-20b#Ollama#MCP#로컬 AI#AI 에이전트#오픈소스 LLM#AI 통합#LLM 로컬 실행#AI 브리지#Python FastAPI#AI 개발 가이드

🚀 Ollama + MCP로 구현하는 로컬 GPT-OSS-20B AI 에이전트

인공지능 모델을 활용한 에이전트 개발은 더 이상 연구실 안의 실험이 아니라, 개발자라면 누구나 직접 구현할 수 있는 현실적인 주제가 되었습니다. 특히 최근 오픈소스로 공개된 GPT-OSS-20B 모델은 높은 성능을 갖추면서도 로컬 환경에서 실행할 수 있어 주목받고 있습니다.

이번 글에서는 Ollama를 통해 GPT-OSS-20B 모델을 로컬에서 손쉽게 실행하고, 이를 MCP(Model Context Protocol) 와 연동하여 실제 도구를 호출하고 작업을 수행할 수 있는 AI 에이전트로 확장하는 방법을 살펴봅니다.
단순히 질문에 답변하는 수준을 넘어, 파일 탐색·웹 검색과 같은 기능까지 수행할 수 있는 구조를 직접 구현해봄으로써, 로컬 환경에서도 클라우드 의존 없이 강력한 AI 에이전트를 구축할 수 있는 가능성을 확인해보겠습니다.


📌 프로젝트 개요

이번 프로젝트의 목표는 로컬 환경에서 실행되는 GPT-OSS-20B 모델을 Ollama와 MCP(Model Context Protocol) 로 연동하여, 단순한 대화형 모델을 넘어 실제 작업을 수행할 수 있는 AI 에이전트로 확장하는 것입니다.

Ollama CLI를 통해 로컬에서 대형 언어 모델을 실행하고, MCP 서버와 Python 스크립트를 연결함으로써 사용자는 인터넷 연결 없이도 안전하게 AI와 상호작용할 수 있습니다. 특히 gpt-oss:20b 모델을 예시로, 질문에 답변하는 것뿐만 아니라 파일 읽기·폴더 탐색·웹 검색과 같은 기능까지 수행하도록 설계되었습니다.

구성 요소는 다음 두 가지로 단순화되어 있습니다.

  • bridge_http.py : Ollama와 MCP를 연결하는 스크립트
  • mcp_server.py : FastMCP 기반으로 동작하며 실제 도구 호출을 담당하는 서버

✨ 주요 기능

  • 완전 로컬 실행 : 인터넷 연결 없이 로컬 환경에서 모델을 실행합니다. 클라우드 의존이 없으므로 안정적인 활용이 가능합니다.
  • 데이터 프라이버시 보장 : 모든 요청과 응답이 로컬에서 처리되어 보안과 개인정보 보호 측면에서 안전합니다.
  • 실시간 도구 호출 : 모델이 필요 시 자동으로 도구를 호출하여 파일 읽기, 폴더 탐색, 웹 검색 등을 수행하고 결과를 대화에 반영합니다.
  • 인터랙티브 채팅 : 세션 종료 전까지 대화 맥락을 유지하며, 연속적이고 단계적인 상호작용이 가능합니다.
  • 효율적인 VRAM 관리 : 종료 시 모델을 자동 언로드하여 GPU 메모리 점유를 최소화합니다.
  • 멀티플랫폼 호환성 : Windows, macOS, Linux 환경에서 동일하게 실행할 수 있습니다.
  • 디버깅 및 확장성 : DEBUG=1 설정으로 상세 로그를 확인할 수 있으며, MCP 서버에 새로운 도구를 추가해 맞춤형 AI 에이전트로 확장할 수 있습니다.

🏗️ 아키텍처 및 작동 방식

1. Ollama CLI & 로컬 모델

  • ollama pull gpt-oss:20b 명령으로 모델 다운로드
  • ollama serve 실행 후, 내부 서버(Localhost API)로 모델과 통신

2. MCP 서버 (mcp_server.py)

  • FastMCP 기반으로 구축
  • stdio 기반 프로토콜로 브리지와 연결
  • 제공 도구: get_time, list_files_in_folder, read_file, web_search

3. 브리지 (bridge_http.py)

  • MCP 클라이언트 역할
  • Ollama HTTP API와 MCP 서버를 연결하는 중간 계층
  • 모델 응답을 분석해 도구 호출 여부를 결정하고, MCP 서버 실행 후 결과를 다시 모델에 전달
  • 종료 시 keep_alive=0 옵션으로 모델 언로드하여 VRAM 해제
  • 환경 변수(OLLAMA_HOST, OLLAMA_MODEL, DEBUG)로 설정 가능

🔄 작동 흐름

  1. 코드 실행
  2. 사용자가 프롬프트 입력 입력
  3. 브리지가 Ollama에 요청 전송
  4. 모델이 도구 호출 필요 시 MCP 서버 실행
  5. MCP 서버에서 결과 반환
  6. 브리지가 결과를 모델에 전달 → 최종 응답 생성

※ 기본 응답은 한국어, 필요 시 시스템 프롬프트 수정으로 영어 전환 가능


⚡ 사용 방법 (간단 안내)

아래 저장소에 이 프로젝트의 전체 코드와 실행 가이드가 제공되어 있습니다. 간단한 단계만 따라 하시면 로컬에서 바로 실행해보실 수 있습니다.

1. 필수 구성 요소 준비

  • Ollama CLI 설치 및 실행 (ollama pull gpt-oss:20b → ollama serve)
  • Python 3.10 이상 환경 (가상환경 권장)
  • 해당 저장소 클론 또는 ZIP 다운로드

2. 저장소 클론 및 환경 설정

git clone https://github.com/AIMIZING/ollama_cli_mcp.git
cd ollama_cli_mcp
python -m venv .venv
source .venv/bin/activate  # (윈도우에서는 .venv\Scripts\activate)
pip install -r requirements.txt

3. (선택) 환경 변수 설정

# Windows (PowerShell 예시)
$env:OLLAMA_HOST="http://127.0.0.1:11434"
$env:OLLAMA_MODEL="gpt-oss:20b"
$env:DEBUG="1"
  • OLLAMA_HOST: Ollama의 API 주소 (기본값 포함)
  • OLLAMA_MODEL: 사용할 모델 지정
  • DEBUG=1: 디버그 로그 활성화

4. 브리지 실행

python bridge_http.py
  • 브리지가 Ollama와 MCP 서버를 연결하며 동작합니다.
  • 종료 시 자동으로 모델 언로드 및 VRAM 해제가 이루어집니다.

5. 예시 상호작용

브리지가 실행된 터미널에서 다음과 같은 명령을 입력해보세요:

  • 현재 시간 알려줘
  • asset 폴더의 파일 목록 보여줘
  • asset/apple_research.pdf 파일 내용 읽어줘
  • 웹에서 "Python 튜토리얼" 검색해줘

마무리

이 프로젝트는 로컬에서 실행되는 LLM과 MCP를 결합하여, 클라우드에 의존하지 않고도 안전하게 활용할 수 있는 AI 어시스턴트를 구현하는 실험적 시도입니다. 단순한 대화형 모델을 넘어 파일 탐색, 문서 읽기, 웹 검색과 같은 기능까지 수행할 수 있도록 확장함으로써, 로컬 AI의 새로운 가능성을 제시합니다.

현재는 기본 도구 중심으로 동작하지만, 앞으로는 멀티모달 지원과 다양한 확장을 통해 활용 범위를 더욱 넓혀갈 계획입니다.

감사합니다.

작성자 : AIMIZING.

관련 글

MCP2025-06-29PINNED

Model Context Protocol(MCP)이란? 도구를 통해 LLM을 AI 에이전트로 만드는 기술

MCP로 AI 에이전트 구현하는 방법