Hello Llama

build private AI agent

OLLAMA+MCP Agent: Chat GUI sample code

by ·


OLLAMA MCP Agent 시리즈 목차


Ollama 와 MCP 를 이용해서 AI Agent 를 만드는 방법에 관한 포스트 2편을 작성했습니다.

이전 포스트는 CLI(command line interface) 를 이용해서 AI agent 를 실행하는 방법을 사용했습니다. 이 방식은 간단한 구현이 장점이지만 아무래도 사용하기에는 불편한 점이 많고 멀티 모달 같은 형태로 확장하기에 제한이 많습니다.

또한 간단한 테스트, LLM 응답을 분석하기에는 CLI 환경은 어울리지 않습니다. 그래서 이번 포스트에서는 GUI 기반의 AI Agent 코드를 소개합니다.

ollama-mcp-chat 프로젝트는 PyQt6 기반의 GUI 기반으로 ollama-MCP AI Agent 를 동작시킵니다.



GUI – AI Chat Agent 설치


GUI 기반의 AI Chat Agent 코드는 github 에서 다운로드 받을 수 있습니다.

# 또는 terminal 에서 아래 명령어 수행해서 repository clone
git clone https://github.com/godstale/ollama-mcp-chat
cd ollama-mcp-chat


예제코드 실행에 필요한 라이브러리 설치가 필요합니다. ollama-mcp-chat 예제는 uv 패키지 관리자를 지원합니다. termial 또는 PowerShell 환경에서 아래 명령어를 실행합니다.

# Using pip
pip install uv

# Or using curl (Unix-like systems)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using PowerShell (Windows)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"


uv 를 설치, 예제코드를 실행하기 위한 가상환경을 만들고 실행합니다. 그리고 아래 순서대로 프로젝트를 설치할 수 있습니다. (terminal 환경에서 실행)

# Install dependencies
uv sync


ollama 에 LLM 모델을 다운로드해야 합니다. 이때 주의할 점이 하나가 있습니다. 반드시 tools calling 기능을 지원하는 모델을 받아야 합니다. 그렇지 않으면 MCP 설정을 추가해도 LLM 이 도구를 사용하지 않을 것입니다.

  • 2025.05 기준으로 ollama 에서는 Qwen3 모델이 적합해 보입니다.
    • llama4, llama3.3, mistral, MFDoom/deepseek-r1-tool-calling 등 툴을 지원하는 LLM 이 꽤 있습니다. 하지만 MCP 와 제대로 동작하지는 않는 모델들도 있는것 같습니다.
  • 그래픽카드 메모리 용량에 맞춰 모델을 선택세요. (ollama 모델 페이지 참고)
  • 이 포스트에서는 RTX4070 SUPER 12G 그래픽카드에 맞춰 14b (9.3 GB) 모델을 사용합니다.
# Install Ollama (refer to https://ollama.ai for platform-specific installation)
# Download LLM model which supports Tool calling feature
ollama pull qwen3:14b



Chat GUI 기능소개 및 테스트


아래 명령어를 실행하면 Chat window 를 보실 수 있습니다.

uv run main.py


화면의 왼쪽 패널에서는 챗 히스토리, MCP 서버, AI 설정 관리를 할 수 있습니다.

  • Chat history
    • 오른쪽에서 실행한 채팅이 기록됩니다.
    • AI 실행 중간에 생성된 로그들이 화면에도 표시되고, chat history 에도 기록됩니다.
    • 프로젝트 root 폴더의 chat_history.json 에 저장됩니다.
    • 새 채팅 버튼을 눌러 채팅을 새로 생성할 수 있습니다.
  • MCP servers
    • MCP server 를 추가, 삭제할 수 있습니다
    • smithery.ai 와 같은 MCP repository 에서 복사한 json 설정값을 여기서 추가할 수 있습니다
  • AI setttings
    • 채팅을 초기화할 때 사용하는 설정값을 변경할 수 있습니다.
    • AI service 는 변경 불가, LLM model 은 변경 가능
      • 반드시 ollama 로 미리 다운로드 후 설정해야 합니다
    • temperature 값은 0.0 ~ 1.0 까지 설정이 가능합니다.
      • LLM에서 생성되는 답변의 창의성, 다양성, 무작위성을 조절하는 하이퍼파라미터입니다.
      • 값이 낮을수록(예: 0.1~0.3) 일관되고 예측 가능하며, 정답에 가까운 보수적인 답변
      • 값이 높을수록(예: 0.7~1.0 이상) 다양하고 창의적이며, 예측 불가능한 답변
    • timeout
      • 특정 시간동안 응답이 없는 경우 동작 취소
      • 복잡한 작업 또는 시스템이 느린 경우 값을 충분히 크게 설정하세요
    • prompt
      • 채팅을 시작할 때 LLM 에게 도구를 사용해서 답변하도록 설정한 system prompt


오른쪽 main 영역은 채팅이 표시되는 영역입니다.

  • 사용자의 질문이 입력되면 답변을 하기까지 AI 생성하는 추론 과정이 모두 표시됩니다.
  • 화면에 표시된 내용은 chat history 에 기록됩니다.
  • 이전 채팅 내용은 조회만 가능합니다.


오른쪽 하단은 채팅 입력창입니다.

  • 현재 활성화된 채팅인 경우에만 채팅을 입력할 수 있습니다.
  • 채팅이 길어지는 경우 새 채팅을 생성하세요
  • clear 버튼은 단지 화면 출력만 지웁니다.



Chat GUI 코드


프로젝트의 파일은 아래와 같이 구성되었습니다. 

프로젝트 루트/
├── main.py                # 프로그램 실행 진입점
├── app_settings.py        # 앱 설정 관리 로직
├── app_settings.json      # 앱 설정 데이터(JSON)
├── chat_history.json      # 채팅 기록 데이터(JSON)
├── constants.py           # 상수 정의
├── worker.py              # 백그라운드 작업 처리(스레드 등)
├── README.md              # 프로젝트 설명서
├── setup.py, pyproject.toml, uv.lock  # 패키지/환경 설정 파일
├── agent/
│   ├── chat_history.py    # 채팅 기록 관리 클래스
│   ├── llm_ollama.py      # Ollama LLM 연동 로직
│   └── __init__.py
├── mcp_server/
│   ├── mcp_manager.py             # MCP 서버 관리
│   ├── mcp_server_file_manager.py # 파일 관리 MCP 서버 예시
│   ├── mcp_server_weather.py      # 날씨 MCP 서버 예시
│   └── __init__.py
├── ui/
│   ├── chat_window.py     # 메인 GUI(채팅창, 설정, 서버 목록 등)
│   ├── __init__.py
│   └── widgets/
│       ├── ai_settings_dialog.py      # AI 설정 다이얼로그
│       └── mcp_server_dialog.py       # MCP 서버 설정 다이얼로그
└── 기타: .gitignore, LICENSE...


파일별 코드 소개

  • main.py
    • 프로젝트의 실행 진입점 역할
    • 윈도우 창을 생성하기 위해 ChatWindow 생성
  • chat_window
    • ChatWindow 객체가 실행되면서 GUI 화면 초기화 및 출력
    • 모든 GUI 이벤트 처리
    • 초기화 과정에서 Worker thread 생성
      • worker thread 와는 queue 를 이용해서 데이터 송수신
    • timer 를 생성해서 queue 로 들어오는 이벤트 처리 (checkWorkerResult)
  • worker.py
    • 앱이 시작할 때 worker thread 가 생성되고 초기화 됨
    • 초기화 과정에서 MultiServerMCPClient 를 생성하고 동작시킴
    • 이후 OllamaAgentManager 를 통해 agent 를 생성
    • 사용자가 채팅을 입력하면 OllamaAgentManager 를 통해 LLM 이 처리
    • LLM 처리 결과를 받아서 queue 를 통해 ChatWindow 로 전달
  • llm_ollama.py
    • OllamaAgentManager 클래스를 정의
    • worker 에 의해서 초기화 시작
    • 실행할 모델을 지정해서 ChatOllama 인스턴스를 생성
    • system prompt 와 temperature, 사용자 입력 메시지를 전달해서 처리
    • 생성된 결과를 전달


ollama-mcp-chat 프로젝트는 파이썬을 이용해서 GUI 기반으로 Ollama/MCP chat agent 를 만들 수 있도록 base code 를 제공합니다.

파이썬, PyQt 기반의 GUI 프로그래밍은 AI coding 으로 기능을 구현하기 쉬우므로 보다 빠르고 효율적으로 여러분이 원하는 프로젝트로 확장하실 수 있을겁니다.



참고자료

GitHub – godstale/ollama-mcp-chat: Ollama MCP Chat is a desktop chatbot application that integrates Ollama’s local LLM models with MCP (Model Context Protocol) servers
Ollama MCP Chat is a desktop chatbot application that integrates Ollama’s local LLM models with MCP (Model Context Protocol) servers – godstale/ollama-mcp-chat
qwen3
Qwen3 is the latest generation of large language models in Qwen series, offering a comprehensive suite of dense and mixture-of-experts (MoE) models.

Tags:

You may also like...

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다

이 사이트는 Akismet을 사용하여 스팸을 줄입니다. 댓글 데이터가 어떻게 처리되는지 알아보세요.