MCP 도구 키트

고정밀 수직 AI 에이전트 구축을 위한 모듈식 서버 구현입니다. 고정밀 수직 AI 에이전트 구축에 사용되지만, 배포를 통해 일반 도구 기능에 접근할 수 있습니다.

Python MCP SDK만 사용할 때보다 코드 사용량이 50% 이상 줄었습니다.

이 접근 방식의 이점

Claude의 인지 부하 감소 : Claude는 도구 호출 순서에 대해 추론할 필요가 없습니다.
도메인 지식 캡슐화 : 에이전트는 특정 수직 분야에서 작업을 잘 수행하는 방법에 대한 도메인별 논리를 포함할 수 있습니다.
오류 처리 간소화 : 에이전트는 Claude의 개입 없이 내부적으로 오류를 처리하고 재시도할 수 있습니다.
복잡한 워크플로우 활성화 : 개별 도구 호출을 통해 조정하기 어려운 다단계 프로세스
대화 흐름 유지 : 사용자는 기본 시스템의 복잡성에 노출되지 않습니다.

예시 시나리오

클로드가 수직 에이전트를 호출하는 구체적인 예는 다음과 같습니다.

지엑스피1

개요

MCP 통합 서버는 Claude가 다음을 포함한 다양한 외부 시스템 및 도구와 상호 작용할 수 있는 통합 인터페이스를 제공합니다.

파일 시스템 작업 : 파일 읽기, 쓰기 및 조작
시간 도구 : 다른 시간대의 현재 시간을 가져오고 시간대 간 변환합니다.
순차적 사고 : 역동적이고 반성적인 문제 해결을 위한 도구
Brave Search : 웹 및 로컬 검색 기능
브라우저 자동화 : Playwright를 통한 완벽한 브라우저 제어
세계은행 API : 경제 및 개발 데이터 접근
뉴스 API : 글로벌 뉴스 소스 및 기사에 접근
PowerPoint : PowerPoint 프레젠테이션 만들기 및 조작
Excel : Excel 스프레드시트 만들기 및 조작
야후 파이낸스 : 주식 시장 및 금융 데이터
FRED : 연방준비제도 이사회 경제 데이터
에이전트 기능 : 복잡한 작업을 수행하는 자율 에이전트를 생성하고 배포합니다.
그리고 훨씬 더 많은 전문 도구

총 123개의 도구 사용 가능

빠른 시작 가이드: 기본 도구를 사용하여 첫 번째 MCP 서버 배포

참고: git( https://git-scm.com/downloads )과 Docker( https://www.docker.com/products/docker-desktop/ )를 다운로드하고 실행 중인지 확인하세요. 또한 git 실행 파일이 path에 추가되었는지 확인해야 합니다(이 README 파일 끝부분에 있는 지침 참조).

Docker 배포(권장 및 가장 안정적)

저장소를 복제합니다.

clone https://github.com/getfounded/mcp-tool-kit.git
cd mcp-tool-kit

그런 다음 두 가지 방법 중 하나로 Docker를 사용할 수 있습니다. 옵션 1 - docker-compose 사용:

docker-compose up

옵션 2 - 직접 Docker 명령:

docker run -p 8000:8000 -v ~/documents:/app/documents getfounded/mcp-tool-kit:latest

저장소에는 사용할 수 있는 샘플 Claude 데스크톱 구성 파일( claude_desktop_config.json )이 포함되어 있습니다.

{
  "mcpServers": {
    "unified": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-tool-kit-mcp-server",
        "python",
        "-u",
        "mcp_unified_server.py"
      ],
      "useStdio": true
    }
  }
}

도커 문제 해결

Docker 실행 중 오류가 발생하는 경우, Claude 데스크톱 구성 파일의 이미지 이름이 잘못되었을 가능성이 높습니다. 일반적인 해결 방법은 다음 JSON을 사용하여 구성하는 것입니다.

{
  "mcpServers": {
    "unified": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-tool-kit-mcp-server-1",
        "python",
        "-u",
        "mcp_unified_server.py"
      ],
      "useStdio": true
    }
  }
}

pip를 통해 설치

# Simple installation
pip install mcptoolkit

# Launch the server with default configuration
mcptoolkit-server

로컬 서버 기본 구성:

{
  "tools": [
    {
      "name": "MCP Toolkit",
      "url": "http://localhost:8000"
    }
  ],
  "settings": {
    "allowed_directories": ["~/Documents", "~/Downloads"],
    "default_tools": ["MCP Toolkit"]
  }
}

Claude Desktop을 구성하여 서버에 액세스하세요

Claude 데스크톱 앱 열기
파일 > 설정 > 개발자 > 구성 편집으로 이동하세요.
'claude_desktop_configuration.json' 파일을 추가합니다.
구성을 저장합니다
새 도구가 통합된 MCP 서버를 다시 시작하세요.
Claude Desktop 앱을 다시 시작하고 엽니다(Windows 사용자의 경우 작업 관리자를 사용하여 모든 Claude 인스턴스의 작업을 종료해야 함)

이 구성을 Claude 데스크톱 앱으로 가져오거나, 이를 참조하여 사용자 고유의 구성을 만들 수 있습니다.

이제 API 키나 복잡한 설정 없이도 파일 작업, 웹 검색, 시간 도구 등 강력한 기능에 즉시 액세스할 수 있습니다.

환경 변수 설정

저장소를 복제한 후에는 환경 변수를 구성하는 데 두 가지 옵션이 있습니다.

옵션 1: 대화형 설정 스크립트

환경 변수를 설정하는 방법을 안내하는 설정 스크립트를 실행하세요.

python setup_env.py

이 스크립트는 사용자의 구성을 사용하여 저장소에 .env 파일을 생성합니다.

옵션 2: 수동 구성

또는 다음 변수를 사용하여 저장소 루트에 .env 파일을 수동으로 만들 수 있습니다.

# API Keys for external services
BRAVE_API_KEY=your_brave_api_key
NEWS_API_KEY=your_news_api_key
FRED_API_KEY=your_fred_api_key

# Application configuration
STREAMLIT_APPS_DIR=/path/to/streamlit/apps
MCP_FILESYSTEM_DIRS=/path/to/allowed/dir1,/path/to/allowed/dir2
MCP_LOG_LEVEL=info

클로드 프롬프트 샘플

설정이 완료되면 다음과 같은 메시지를 통해 Claude에게 도구 사용을 요청할 수 있습니다.

"최신 AI 연구 논문을 웹에서 검색하고 결과를 요약하세요."
"세 장의 슬라이드로 기후 변화에 대한 파워포인트 프레젠테이션을 만들어 보세요."
"날씨 확인 에이전트를 사용하여 도쿄의 현재 상황을 알려주세요."
"Quick_Lookup 에이전트를 사용하여 양자 컴퓨팅의 발전에 대해 알아볼 수 있나요?"
"QuickBooks 송장 데이터를 다운로드하고 지난 분기의 수익을 분석해 보세요."
"이러한 세부 정보와 가격으로 Shopify 스토어에 제품을 설정하세요."
"Yahoo Finance를 사용하여 Tesla의 현재 주가와 과거 데이터를 확인하세요."
"지난 5년간의 FRED 경제 데이터를 사용하여 인플레이션 추세를 분석합니다."
"[웹사이트 URL]에서 브라우저 자동화를 사용하여 이 양식을 작성하세요."
"다운로드 폴더에 있는 'project_notes.txt'라는 텍스트 파일을 읽어보세요."
"기술에 대한 최신 뉴스 헤드라인을 받아보세요."

사용 가능한 도구

파일 시스템 도구

read_file : 파일의 내용을 읽습니다
read_multiple_files : 여러 파일을 동시에 읽습니다.
write_file : 파일을 생성하거나 덮어씁니다.
edit_file : 파일에 줄 기반 편집을 수행합니다.
create_directory : 새로운 디렉토리를 생성합니다
list_directory : 디렉토리 내용 가져오기
directory_tree : 재귀적 트리 뷰를 가져옵니다
move_file : 파일/디렉토리를 이동하거나 이름을 바꿉니다.
search_files : 패턴과 일치하는 파일을 검색합니다.
get_file_info : 파일 메타데이터 가져오기
list_allowed_directories : 허용된 디렉토리를 나열합니다.
브라우저 자동화:
- playwright_launch_browser : 새 브라우저 인스턴스를 시작합니다.
- playwright_navigate : URL로 이동
- playwright_screenshot : 스크린샷 찍기
- playwright_click : 요소를 클릭합니다.
- playwright_fill : 입력 필드 채우기
- playwright_evaluate : JavaScript 실행
- playwright_get_content : 페이지의 HTML 콘텐츠를 가져옵니다

에이전트 도구

run_agent : 매개변수를 사용하여 등록된 에이전트를 실행합니다.
list_agents : 사용 가능한 모든 에이전트와 해당 메타데이터를 나열합니다.

재무 데이터 도구

야후 파이낸스:
- yfinance : 주식 시세 및 과거 데이터를 받아보세요
- yfinance_get_quote : 현재 주식 시세를 받아보세요
- yfinance_get_history : 과거 주식 데이터 가져오기
- yfinance_get_info : 자세한 회사 정보 얻기
- yfinance_get_options : 옵션 체인 데이터 가져오기
- yfinance_get_recommendations : 분석가 추천 받기
FRED(연방준비제도이사회 경제 데이터):
- fred_get_series : 경제 데이터 시리즈 가져오기
- fred_get_series_info : 시리즈에 대한 메타데이터 가져오기
- fred_search : 경제 데이터 시리즈 검색
- fred_get_category : 카테고리별로 데이터 찾아보기
- fred_get_releases : 경제 데이터 발표 받기
- fred_get_sources : 데이터 소스 가져오기

시간 도구

get_current_time : 지정된 시간대의 현재 시간을 가져옵니다.
convert_time : 시간대 간 시간 변환

순차적 사고

sequentialthinking : 단계별 사고 과정을 사용하여 복잡한 문제를 분해하는 도구

브레이브 서치

brave_web_search : 웹 검색 수행
brave_local_search : 지역 업체 및 장소 검색

세계은행 API

worldbank_get_indicator : 국가별 지표 데이터 가져오기

뉴스 API

news_top_headlines : 주요 뉴스 헤드라인을 받아보세요
news_search : 뉴스 기사 검색
news_sources : 사용 가능한 뉴스 소스 나열

파워포인트 도구

ppt_create_presentation : 새로운 PowerPoint 프레젠테이션을 만듭니다
ppt_open_presentation : 기존 프레젠테이션을 엽니다
ppt_save_presentation : 프레젠테이션 저장
ppt_add_slide : 새 슬라이드 추가
ppt_add_text : 슬라이드에 텍스트 추가
ppt_add_image : 슬라이드에 이미지 추가
ppt_add_chart : 슬라이드에 차트 추가
ppt_add_table : 슬라이드에 표 추가
ppt_analyze_presentation : 프레젠테이션 구조 분석
ppt_enhance_presentation : 개선 사항 제안
ppt_generate_presentation : 텍스트에서 프레젠테이션을 생성합니다.
ppt_command : 자연어 명령 처리

사용 가능한 도구의 전체 목록을 보려면 설명서를 참조하거나 도구 디렉터리를 탐색하세요. 사용 가능한 도구의 전체 목록을 보려면 설명서를 참조하거나 도구 디렉터리를 탐색하세요.

새로운 도구 모듈 추가

tools 디렉토리에 새 파일을 만듭니다(예: my_tool.py )
기존 모듈 패턴을 따르세요.
- 서비스 클래스 생성
- 도구 기능 정의
- 등록 기능 구현
mcp_unified_server.py 를 업데이트하여 새 모듈을 가져오고 등록하세요.

기존 도구 모듈 확장

서비스 클래스에 새로운 메서드 추가
새로운 도구 기능 추가
새로운 도구를 포함하도록 등록 기능을 업데이트하세요.

Docker를 사용한 개발

일관된 환경을 보장하기 위해 개발에 Docker를 사용할 수 있습니다.

# Build a development image
docker build -t mcp-tool-kit:dev .

# Run with source code mounted for development
docker run -p 8000:8000 \
    -v $(pwd):/app \
    -v ~/documents:/app/documents \
    mcp-tool-kit:dev

이렇게 하면 로컬 저장소가 컨테이너에 마운트되므로 코드 변경 사항이 (대부분의 파일에 대해) 즉시 반영됩니다.

철학적 관점: 인간-AI 인지 파트너십

MCP 툴킷은 인간 지능과 AI 시스템 간의 관계를 개념화하는 방식에 있어 패러다임의 전환을 보여줍니다. 이 프레임워크는 AI를 단순한 작업 자동화 도구로 보는 것이 아니라, 인간의 전략적 사고와 AI의 운영 역량이 심오한 방식으로 상호 보완되는 인지적 파트너십을 구축합니다.

에이전트 아키텍처는 혁신적인 비전을 구현합니다. AI 시스템은 맥락을 독립적으로 해석하고, 제한된 매개변수 내에서 결정을 내리고, 복잡한 일련의 동작을 실행할 수 있으며, 이 모든 것이 인간의 감독과 전략적 방향을 유지하는 데 도움이 됩니다. 이는 단순한 기술적 진보가 아니라 인간과 기계의 협업을 위한 근본적으로 새로운 모델을 의미합니다.

이처럼 끊임없이 변화하는 인지 환경에서 가장 성공적인 구현은 기술적 잠재력과 인간 능력의 균형을 신중하게 맞춰 인간의 의사 결정과 창의성을 대체하는 것이 아니라 향상시키는 인터페이스를 만드는 것입니다.

문제 해결

모듈이 로드되지 않음 : 가져오기 경로 및 종속성을 확인하세요
API 키 오류 : .env 파일에서 API 키를 확인하세요
권한 오류 : MCP_FILESYSTEM_DIRS 에서 허용된 디렉토리를 확인하세요.
연결 오류 : 서버가 실행 중이고 포트에 액세스할 수 있는지 확인하세요.
에이전트가 감지되지 않았습니다 . 에이전트 파일이 올바른 디렉토리에 있고 필요한 형식을 따르는지 확인하세요.
경로 문제 : 아래 지침에 따라 git이 경로에 추가되었는지 확인하세요.

#Windows에서 PATH에 Git을 추가하려면 다음 단계를 따르세요.

Git 설치 위치 찾기: 시스템에서 Git이 설치된 경로를 확인하세요. 일반적인 경로는 표준 Git 설치의 경우 C:\Program Files\Git\bin\git.exe와 C:\Program Files\Git\cmd이고, Windows용 GitHub 또는 GitHub Desktop을 통해 Git을 설치한 경우 C:\Users<사용자 이름>\AppData\Local\GitHub\PortableGit_\bin과 C:\Users<사용자 이름>\AppData\Local\GitHub\PortableGit_\cmd입니다.
환경 변수 편집: 제어판을 통해 또는 시작 메뉴에서 "시스템 환경 변수 편집"을 검색하여 "환경 변수 편집" 앱을 엽니다. "시스템 변수" 섹션에서 "경로" 변수를 찾아 "편집..."을 클릭하고 Git 실행 파일 및 명령 파일의 경로를 추가합니다. 경로를 구분하는 세미콜론(;) 주위에 공백이 없는지 확인합니다.
변경 사항 저장: Git 경로를 추가한 후 "확인"을 클릭하여 변경 사항을 저장합니다. 명령 프롬프트 창을 닫았다가 다시 열어 새 PATH 설정을 적용합니다.
설치 확인: 명령 프롬프트를 열고 git --version을 실행하여 명령줄에서 Git에 접근할 수 있는지 확인합니다.

특허

MCP 통합 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다.

감사의 말

이 프로젝트는 여러 개의 오픈 소스 라이브러리와 API를 사용합니다.

Claude AI 어시스턴트를 위한 MCP SDK
뉴스 접근을 위한 NewsAPI
웹 검색을 위한 Brave Search API
세계은행 경제 데이터 API
파워포인트 조작을 위한 python-pptx
Excel 스프레드시트용 XlsxWriter

MCP Unified Server

Integrations