MCP 서버 박스
설명
MCP Server Box는 Box API와 통합되어 파일 검색, 텍스트 추출, AI 기반 쿼리, 데이터 추출 등 다양한 작업을 수행하는 Python 프로젝트입니다. box-sdk-gen 라이브러리를 활용하며 Box 파일 및 폴더와 상호 작용하는 도구 세트를 제공합니다.
모델 컨텍스트 프로토콜(MCP)은 모델이 다양한 데이터 소스 및 서비스와 상호 작용하는 방식을 표준화하도록 설계된 프레임워크입니다. 이 프로젝트에서는 MCP를 사용하여 Box API와의 원활한 통합을 촉진하고, Box 파일 및 폴더에 대한 효율적이고 확장 가능한 작업을 지원합니다. MCP 서버 Box 프로젝트는 고급 AI 및 머신러닝 기술을 사용하여 Box 데이터를 관리하고 처리하는 강력하고 유연한 솔루션을 제공하는 것을 목표로 합니다.
Related MCP server: Box MCP Server
구현된 도구
Box API 도구
box_who_am_i
현재 사용자 정보를 가져오고 연결 상태를 확인하세요.
반환: 사용자 정보 문자열
box_authorize_app_tool
Box 애플리케이션 승인 절차를 시작하세요.
반환: 승인 상태 메시지
box_search_tool
Box에서 파일을 검색하세요.
매개변수:
query(str): 검색할 쿼리입니다.file_extensions(List[str], 선택 사항): 결과를 필터링할 파일 확장자입니다.where_to_look_for_query(List[str], 선택 사항): 검색할 위치(예: 이름, 설명, 파일 내용, 주석, 태그).ancestor_folder_ids(List[str], 선택 사항): 검색할 폴더 ID 목록입니다.
반환: 검색 결과는 파일 이름과 ID를 줄바꿈으로 구분한 목록으로 표시됩니다.
box_read_tool
Box 파일의 텍스트 내용을 읽습니다.
매개변수:
file_id(str): 읽을 파일의 ID
반환: 파일 내용
box_ask_ai_tool
Box AI에 파일에 대해 문의하세요.
매개변수:
file_id(str): 파일의 IDprompt(str): AI에 대한 질문
반환: AI 응답
box_hubs_ask_ai_tool
Box AI에 허브에 대해 문의해 보세요. 현재 API를 통해 허브 ID를 확인할 수 있는 방법이 없으므로, 이 도구를 사용하려면 ID를 알아야 합니다. 이 문제는 향후 수정될 예정입니다.
매개변수:
hubs_id(str): 허브의 IDprompt(str): AI에 대한 질문
반환: AI 응답
box_search_folder_by_name
이름으로 폴더를 찾으세요.
매개변수:
folder_name(str): 폴더 이름
반환: 폴더 ID
box_ai_extract_data
AI를 사용하여 파일에서 데이터를 추출합니다.
매개변수:
file_id(str): 파일의 IDfields(str): 추출할 필드
반환: JSON 형식으로 추출된 데이터
box_list_folder_content_by_folder_id
폴더 내용을 나열합니다.
매개변수:
folder_id(str): 폴더의 IDis_recursive(bool): 재귀적으로 나열할지 여부
반환: ID, 이름, 유형 및 설명이 포함된 JSON 형식의 폴더 콘텐츠
box_manage_folder_tool
Box에서 폴더를 만들고, 업데이트하고, 삭제합니다.
매개변수:
action(str): 수행할 작업: "create", "delete" 또는 "update"folder_id(str, 선택 사항): 폴더의 ID(삭제/업데이트에 필요)name(str, 선택 사항): 폴더 이름(생성 시 필수, 업데이트 시 선택 사항)parent_id(str, 선택 사항): 상위 폴더 ID(생성 시 필수, 업데이트 시 선택 사항)description(str, 선택 사항): 폴더 설명(업데이트 시 선택 사항)recursive(bool, 선택 사항): 재귀적으로 삭제할지 여부(delete의 경우 선택 사항)
반환: 폴더 세부 정보가 포함된 상태 메시지
box_upload_file_tool
=======
매개변수:
file_id(str): 읽을 파일의 ID입니다.
반환값: 파일의 텍스트 내용.
box_ask_ai_tool
단일 파일에 대한 Query Box AI입니다.
매개변수:
file_id(str): 파일 식별자.prompt(str): AI에 대한 쿼리 또는 지시.
반환: 파일 내용을 기반으로 한 AI 응답입니다.
box_ask_ai_tool_multi_file
여러 파일을 사용하여 Box AI 쿼리하기.
매개변수:
file_ids(List[str]): 파일 ID 목록입니다.prompt(str): 집계된 콘텐츠를 기반으로 한 AI에 대한 지침입니다.
반환: 제공된 모든 파일을 고려하여 AI가 생성한 답변입니다.
box_search_folder_by_name
Box에서 폴더 이름을 찾아 보세요.
매개변수:
folder_name(str): 폴더의 이름.
반환: 일치하는 폴더에 대한 정보(이름 및 ID)
box_ai_extract_data
AI를 사용하여 파일에서 특정 필드를 추출합니다.
매개변수:
file_id(str): 파일의 ID입니다.fields(str): 추출할 필드의 쉼표로 구분된 목록입니다.
반환: JSON 문자열 형식으로 추출된 데이터입니다.
box_list_folder_content_by_folder_id
폴더의 ID를 사용하여 폴더의 내용을 나열합니다.
매개변수:
folder_id(str): 폴더 ID.is_recursive(bool, 선택 사항): 콘텐츠를 재귀적으로 나열할지 여부입니다.
반환: ID, 이름, 유형, 설명을 포함한 JSON 문자열 형태의 폴더 내용입니다.
box_manage_folder_tool
Box에서 폴더를 만들고, 업데이트하고, 삭제합니다.
매개변수:
action(str): 수행할 작업: "생성", "삭제" 또는 "업데이트".folder_id(str, 선택 사항): 폴더 ID(삭제 및 업데이트에 필요).name(str, 선택 사항): 폴더 이름(생성 시 필수, 업데이트 시 선택 사항).parent_id(str, 선택 사항): 상위 폴더 ID(루트의 경우 기본값은 "0")description(str, 선택 사항): 폴더에 대한 설명(업데이트용).recursive(bool, 선택 사항): 재귀적 삭제를 위해.
반환: 폴더 세부 정보가 포함된 상태 메시지입니다.
box_upload_file_from_path_tool
로컬 파일 시스템 경로에서 Box에 파일을 업로드합니다.
매개변수:
file_path(str): 로컬 파일 경로.folder_id(str, 선택 사항): 대상 폴더 ID(기본값은 "0")new_file_name(str, 선택 사항): 새 파일 이름(제공되지 않으면 원래 파일 이름을 사용함).
반환: 업로드된 파일에 대한 세부정보(ID 및 이름) 또는 오류 메시지.
box_upload_file_from_content_tool
컨텐츠를 파일로 Box에 업로드합니다.
매개변수:
content(str | bytes): 업로드할 콘텐츠(텍스트 또는 바이너리).file_name(str): 파일에 지정할 이름입니다.folder_id(str, 선택 사항): 대상 폴더 ID(기본값은 "0")is_base64(bool, 선택 사항): 제공된 콘텐츠가 base64로 인코딩되었는지 여부를 나타냅니다.
반환: 파일 ID와 이름이 포함된 업로드 성공 메시지.
box_download_file_tool
Box에서 파일을 다운로드합니다.
매개변수:
file_id(str): 다운로드할 파일의 ID입니다.save_file(bool, 선택 사항): 파일을 로컬에 저장할지 여부입니다.save_path(문자열, 선택 사항): 파일을 저장할 로컬 경로입니다.
반환: 텍스트 파일의 경우 콘텐츠를 반환하고, 이미지의 경우 base64로 인코딩된 데이터를 반환하고, 다른 유형의 경우 오류 또는 저장 확인 메시지를 반환합니다.
Box Doc Gen 도구
box_docgen_create_batch_tool
Box Doc Gen 템플릿과 로컬 JSON 파일을 사용하여 문서를 생성합니다.
매개변수:
file_id(str): 템플릿 파일 ID.destination_folder_id(str): 생성된 문서를 저장할 폴더 ID입니다.user_input_file_path(str): 입력 데이터가 포함된 JSON 파일의 경로입니다.output_type(str, 선택 사항): 출력 형식(기본값은 "pdf")입니다.
반환값: JSON 문자열 형태의 문서 생성 배치 결과입니다.
box_docgen_get_job_tool
ID로 단일 Doc Gen 작업을 가져옵니다.
매개변수:
job_id(str): 작업 식별자.
반환: JSON 형식 문자열의 작업 세부 정보.
box_docgen_list_jobs_tool
현재 사용자와 관련된 모든 Doc Gen 작업을 나열합니다.
매개변수:
marker(str | None, 선택 사항): 페이지 번호 표시자.limit(int | None, 선택 사항): 반환할 최대 작업 수.
반환값: 예쁘게 인쇄된 JSON 형식의 작업 목록이 페이지별로 나열됩니다.
box_docgen_list_jobs_by_batch_tool
특정 배치에 속하는 Doc Gen 작업을 나열합니다.
매개변수:
batch_id(str): 배치 식별자.marker(str | None, 선택 사항): 페이지 번호 표시자.limit(int | None, 선택 사항): 반환할 최대 작업 수.
반환: JSON 형식의 일괄 작업 세부 정보입니다.
box_docgen_template_create_tool
파일을 Box Doc Gen 템플릿으로 표시합니다.
매개변수:
file_id(str): 템플릿으로 표시할 파일 ID입니다.
반환: 채점 후 템플릿 세부 정보.
box_docgen_template_list_tool
사용 가능한 Box Doc Gen 템플릿을 모두 나열합니다.
매개변수:
marker(str | None, 선택 사항): 페이지 번호 표시자.limit(int | None, 선택 사항): 나열할 템플릿의 최대 개수.
반환: JSON 형식의 템플릿 목록입니다.
box_docgen_template_delete_tool
파일에서 Doc Gen 템플릿 표시를 제거합니다.
매개변수:
template_id(str): 템플릿 식별자입니다.
반환값: JSON으로 삭제 확인.
box_docgen_template_get_by_id_tool
특정 Doc Gen 템플릿의 세부 정보를 검색합니다.
매개변수:
template_id(str): 템플릿 식별자입니다.
반환: JSON 형식의 템플릿 세부정보.
box_docgen_template_list_tags_tool
Box Doc Gen 템플릿과 관련된 모든 태그를 나열합니다.
매개변수:
template_id(str): 템플릿 ID입니다.template_version_id(str | None, 선택 사항): 특정 버전 ID입니다.marker(str | None, 선택 사항): 페이지 번호 표시자.limit(int | None, 선택 사항): 반환할 태그의 최대 개수.
반환: JSON 형식의 태그 목록.
box_docgen_template_list_jobs_tool
특정 템플릿을 사용한 모든 Doc Gen 작업을 나열합니다.
매개변수:
template_id(str): 템플릿 식별자입니다.marker(str | None, 선택 사항): 페이지 번호 표시자.limit(int | None, 선택 사항): 나열할 작업의 최대 개수.
반환: JSON 문자열 형태의 템플릿에 대한 작업 세부 정보입니다.
요구 사항
Python 3.13 이상
Box API 자격 증명(클라이언트 ID, 클라이언트 비밀번호 등)
설치
저장소를 복제합니다.
지엑스피1
아직 설치되지 않았다면
uv설치하세요:2.1 맥OS+리눅스
curl -LsSf https://astral.sh/uv/install.sh | sh2.2 윈도우
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"프로젝트를 생성하고 설정하세요.
3.1 맥OS+리눅스
# Create virtual environment and activate it uv venv source .venv/bin/activate # Lock the dependencies uv lock3.2 윈도우
# Create virtual environment and activate it uv venv .venv\Scripts\activate # Lock the dependencies uv lock루트 디렉토리에
.env파일을 만들고 Box API 자격 증명을 추가합니다.BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret
용법
MCP 서버 실행
MCP 서버를 시작하려면 다음 명령을 실행하세요.
Claude를 클라이언트로 사용
claude_desktop_config.json편집하세요:code ~/Library/Application\ Support/Claude/claude_desktop_config.json구성을 추가합니다.
{ "mcpServers": { "mcp-server-box": { "command": "uv", "args": [ "--directory", "/Users/anovotny/Desktop/mcp-server-box", "run", "src/mcp_server_box.py" ] } } }실행 중이라면 Claude를 다시 시작하세요.
커서를 클라이언트로 사용
커서로 IDE를 엽니다.
설정에서
Cursor settings선택하세요.왼쪽 탐색 창에서
MCP선택하세요.왼쪽 상단에서
Add new global MCP server클릭합니다.다음 JSON을 붙여넣습니다(로컬 값에 맞게 업데이트):
{ "mcpServers": { "box": { "command": "uv", "args": [ "--directory", "/Users/shurrey/local/mcp-server-box", "run", "src/mcp_server_box.py" ] } } }mcp.json 파일을 저장하고 닫은 다음, 필요한 경우 다시 시작합니다.
테스트 실행
이 프로젝트에는 Box API 기능을 검증하는 테스트가 포함되어 있습니다. 테스트를 실행하기 전에 테스트 파일의 파일 및 폴더 ID를 Box 계정의 ID와 일치하도록 업데이트하세요.
테스트 설정
파일 및 폴더 ID 업데이트 :
각 테스트 파일(
tests/디렉토리에 있음)은 Box 파일과 폴더에 대한 하드코딩된 ID를 사용합니다.이 ID를 Box 계정의 유효한 ID로 바꾸세요.
파일 ID 참조 :
예를 들어
tests/test_box_api_read.py에서"1728677291168"유효한 파일 ID로 바꾸세요.
테스트 실행
ID를 업데이트하면 pytest를 사용하여 테스트를 실행할 수 있습니다.
사용 가능한 테스트 모음
test_box_auth.py: 인증 기능을 테스트합니다.test_box_api_basic.py: 기본 Box API 테스트.test_box_api_read.py: 파일 읽기 기능을 테스트합니다.test_box_api_search.py: 검색 기능을 테스트합니다.test_box_api_ai.py: AI 기반 기능을 테스트합니다.test_box_api_file_ops.py: 파일 업로드 및 다운로드 작업을 테스트합니다.추가 테스트에는 폴더 작업과 Doc Gen 기능에 대한 내용이 포함됩니다.
문제 해결
MacOS에서 Claude Desktop으로 MCP 서버를 실행할 때 Error: spawn uv ENOENT 오류가 발생하면 다음을 수행할 수 있습니다.
uv를 제거하고 Homebrew로 다시 설치하세요:
brew install uv또는 구성에서 uv 실행 파일의 전체 경로를 제공하세요.
/Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py
.env 에 있는 Box API 자격 증명이 올바르게 설정되었는지 확인하세요.