MCP Firebase 서버(모델 컨텍스트 프로토콜)
이 서버는 Claude와 같은 대규모 언어 모델(LLM)과 Firebase(Firestore) 간의 다리 역할을 하는 모델 컨텍스트 프로토콜(MCP)을 구현합니다. LLM이 Firestore 컬렉션에서 읽고 쓸 수 있도록 이러한 작업을 MCP "도구"로 노출합니다.
이 서버는 공식 mcp Python SDK를 사용하여 구축되었습니다.
필수 조건
Python 3.7 이상(MCP에서 사용하는
asynccontextmanager및 전체 유형 힌팅 기능의 경우 3.8 이상이 바람직함)Pip(Python 패키지 설치 프로그램) 또는
uv(MCP 문서에서 프로젝트 관리를 위해 권장)Firestore가 활성화된 Firebase 프로젝트.
Firebase 서비스 계정 키 JSON 파일입니다.
Related MCP server: Firebase MCP
설정
복제/다운로드: 로컬 디렉토리에 서버 파일(
mcp_firebase_server.py),requirements.txt등이 있는지 확인하세요.서비스 계정 키:
서버를 인증하려면 Firebase 서비스 계정 키가 필요합니다.
옵션 1(MCP 클라이언트 구성에 권장):
SERVICE_ACCOUNT_KEY_PATH환경 변수를 서비스 계정 JSON 파일의 절대 경로로 설정합니다. MCP 클라이언트에서 서버를 실행할 때 가장 유연한 방법입니다.옵션 2(대체):
SERVICE_ACCOUNT_KEY_PATH환경 변수가 설정되지 않은 경우, 서버는 자체 디렉터리(mcp_firebase_server.py와 동일한 디렉터리)에서serviceAccountKey.json이라는 파일을 찾습니다. 이 방법을 사용하는 경우 키 파일 이름을 그에 맞게 변경하세요.중요: 서비스 계정 키 파일(이름이나 액세스 방법에 관계없이)을 안전하게 보관하고, 프로젝트에 로컬 복사본이 있는 경우 이상적으로
.gitignore에 나열하는 것이 좋습니다.
Firebase 저장소 버킷(선택 사항):
이 서버에서 Firebase 저장소 기능을 사용하려면(현재 이 기능을 사용하는 도구는 없지만 추가할 수 있습니다)
FIREBASE_STORAGE_BUCKET환경 변수를 Firebase 프로젝트의 저장소 버킷 이름(예:your-project-id.appspot.com)으로 설정하세요. 이 값이 설정되어 있으면 서버에서 이 값을 읽고 출력합니다.
가상 환경 만들기(권장):
venv사용:지엑스피1
또는
uv사용하는 경우(MCP 문서에서 새 프로젝트에 대해 제안한 대로):uv venv source .venv/bin/activate # Or similar, depending on your uv setup종속성 설치:
pip사용:pip install -r requirements.txt또는
uv사용하는 경우:uv pip install -r requirements.txt이렇게 하면
mcp[cli]와firebase-admin설치됩니다.
서버 실행
이 MCP 서버를 실행하는 방법에는 여러 가지가 있습니다.
직접 실행( 서버 실행을 간소화하기 위해
run_server.sh스크립트가 제공됩니다. 이 스크립트는 Python 스크립트를 실행하기 전에 가상 환경(venv라는 이름이 지정되어 있고 프로젝트 루트에 있는 경우)을 활성화합니다.먼저 스크립트를 실행 가능하게 만듭니다.
chmod +x run_server.sh그런 다음 스크립트를 사용하여 서버를 실행합니다.
./run_server.sh이는 일반적으로 MCP 클라이언트가 서버를 실행하기 위해 구성되는 방식입니다(아래 "Claude와 함께 사용" 섹션 참조).
**개발 및 검사를 위한 MCP CLI 사용(
mcp dev):mcpCLI(mcp[cli]의 일부로 설치됨)는 개발 서버 및 검사 도구를 제공합니다. 개발 중에는 이 기능을 사용하는 것이 좋습니다.mcp dev mcp_firebase_server.py이렇게 하면 서버가 시작되고, 서버의 기능(도구, 리소스)을 검사하고 테스트 호출을 할 수 있는 웹 인터페이스가 제공됩니다.
MCP 도구 공개
MCPFirebaseServer 라는 이름의 이 서버는 다음 도구를 제공합니다.
1. query_firestore_collection
설명(docstring에서): 지정된 Firestore 컬렉션에서 문서를 검색합니다.
인수:
collection_name(문자열, 필수): 쿼리할 Firestore 컬렉션의 이름입니다.limit(정수, 선택 사항, 기본값: 50): 반환할 문서의 최대 수입니다.
반환: (List[Dict[str, Any]]) 컬렉션의 문서 목록입니다. 각 문서는
id필드를 포함하는 사전입니다. 오류가 발생하면 단일 오류 사전이 포함된 목록을 반환합니다(예:[{"error": "Firestore not initialized..."}]또는[{"error": "Failed to query..."}]).
2. add_document_to_firestore
설명(docstring에서): 지정된 Firestore 컬렉션에 자동 생성된 ID로 새 문서를 추가합니다.
인수:
collection_name(문자열, 필수): 문서가 추가될 Firestore 컬렉션의 이름입니다.document_data(객체/사전, 필수): 추가할 문서를 나타내는 사전입니다.
반환값: (Dict[str, Any])
success(부울)와 성공 시id(문자열) 및message(문자열), 실패 시error(문자열)를 포함하는 사전입니다. 성공 예시:{"success": True, "id": "newDocId", "message": "Document added to 'logs'"}실패 예시:{"success": False, "error": "Firestore not initialized..."}
Claude(또는 다른 MCP 클라이언트)와 함께 사용
이 MCP Firebase 서버는 별도의 프로세스로 실행되도록 설계되었으며, 일반적으로 MCP 클라이언트 애플리케이션(예: Claude Desktop 또는 Windsurf와 같이 MCP 서버를 관리할 수 있는 플랫폼으로 구축된 맞춤형 애플리케이션)에서 실행됩니다. 클라이언트는 로컬에서 실행되는 서버의 경우 일반적으로 stdio (표준 입출력)를 통해 이 서버와 통신합니다.
일반 통합 단계:
서버 가용성: MCP 클라이언트가 실행되거나 프로세스를 시작할 수 있는 시스템에서
mcp_firebase_server.py및 해당 종속성(serviceAccountKey.json포함)에 액세스할 수 있는지 확인하세요.클라이언트 구성: MCP 클라이언트 애플리케이션은
MCPFirebaseServer시작하는 방법을 알 수 있도록 구성해야 합니다. 이 구성에는 일반적으로 다음 사항이 포함됩니다.실행할 명령 (예:
python또는uv run python).해당 명령에 대한 인수 (예:
mcp_firebase_server.py경로).선택적으로, 서버에 필요할 수 있는 환경 변수 (현재 서버는 같은 디렉토리에
serviceAccountKey.json있어야 하지만, 키 경로에 대한 환경 변수가 대안이 될 수 있음).
출시 및 커뮤니케이션:
MCP 클라이언트가 이 서버에서 제공하는 도구를 사용해야 하는 경우 구성된 명령을 사용하여
mcp_firebase_server.py실행합니다.클라이언트와 서버는 MCP 프로토콜(예:
stdio)을 통해 통신합니다. 클라이언트는 사용 가능한 도구(query_firestore_collection,add_document_to_firestore)를 검색하여 호출할 수 있습니다.
개념적 구성 예(Claude Desktop과 같은 MCP 클라이언트용):
많은 MCP 호환 클라이언트 애플리케이션(MCP 문서에 언급된 Claude Desktop 등)은 구성 파일(주로 JSON)을 사용하여 MCP 서버를 시작하고 관리하는 방법을 정의합니다. 정확한 형식은 클라이언트마다 다를 수 있지만, 원리는 비슷합니다.
아래는 MCP 문서에서 볼 수 있는 패턴을 기반으로 한 개념적 예시입니다. 선택한 MCP 클라이언트(Claude Desktop, Windsurf 등)의 특정 구성 메커니즘에 맞게 이 예시를 조정해야 합니다.
구성의 핵심 사항:
"command": 실행할 실행 파일(예:python). 시스템 PATH에 있는지 확인하거나 Python 인터프리터의 전체 경로를 제공하세요."args": 인수 목록입니다. 첫 번째 인수는 일반적으로 실행할 스크립트입니다. 클라이언트가 실행된 위치와 관계없이mcp_firebase_server.py."cwd": 때로는 서버 프로세스의 작업 디렉토리를 지정해야 할 수도 있습니다. 특히 다른 파일에 대한 상대 경로에 의존하는 경우입니다(하지만serviceAccountKey.json경로는 스크립트 자체에 대한 상대 경로이므로 스크립트 경로가 절대 경로인 경우 일반적으로 문제가 없습니다)."env": 환경 변수 전달용입니다. 현재 서버는 자체 경로를 기준으로serviceAccountKey.json파일을 찾는 반면, 구성 가능성이 더 높은 서버에서는 환경 변수를 통해 자격 증명 경로나 기타 설정을 전달하는 것이 일반적인 패턴입니다.
상호작용 흐름(요약):
클라이언트가 서버를 시작합니다. MCP 클라이언트(위의 구성 사용)가
mcp_firebase_server.py시작합니다.서버 초기화: 서버가 Firebase에 연결을 시도합니다.
도구 검색 및 호출: 클라이언트는 필요에 따라
query_firestore_collection이나add_document_to_firestore와 같은 도구를 검색하고 호출합니다.서버 응답: 결과는
stdio를 통해 클라이언트로 다시 전송됩니다.
Claude Desktop 또는 Windsurf에 대한 특정 지침:
Claude Desktop: Claude Desktop을 사용하는 경우 사용자 지정 MCP 서버를 추가하고 구성하는 방법에 대한 설명서를 참조하세요. 위의 JSON 구조는 일반적으로 적용될 수 있는 패턴입니다.
Windsurf: Windsurf가 오케스트레이터이고 MCP 서버 관리를 지원하는 경우, Windsurf는 이러한 외부 도구 서버를 정의하고 실행하는 자체적인 방법을 제공합니다. 자세한 내용은 Windsurf 설명서를 참조해야 하지만, 핵심 정보(명령어,
mcp_firebase_server.py실행 인수)는 동일합니다.
클라이언트에 전용 MCP 서버 관리 UI/구성 파일이 없지만 셸 명령을 실행하고 stdio를 통해 상호 작용할 수 있는 경우 mcp_firebase_server.py 스크립트를 프로그래밍 방식으로 실행한 다음 MCP 클라이언트 라이브러리(예: mcp.client.stdio 에 있는 라이브러리)를 사용하여 통신합니다.
개발 및 테스트
mcp dev mcp_firebase_server.py사용하여 MCP Inspector로 서버를 실행하세요. 이렇게 하면 발견된 도구를 확인하고 대화형으로 테스트할 수 있습니다.MCP 클라이언트가 서버를 시작할 때
serviceAccountKey.json이 올바르게 배치되었는지 또는SERVICE_ACCOUNT_KEY_PATH환경 변수가 설정되었는지 확인하세요.Firebase 초기화 메시지와 런타임 오류를 확인하려면 서버의 콘솔 출력을 확인하세요.
run_server.sh
프로젝트 루트의 run_server.sh 스크립트는 다음을 위해 설계되었습니다.
자신의 위치를 확인하고 현재 디렉토리를 해당 위치로 변경합니다.
프로젝트 루트에
venv라는 Python 가상 환경이 있으면 찾아 활성화합니다.python인터프리터를 사용하여mcp_firebase_server.py스크립트를 실행합니다(활성화된 venv에서 실행하는 것이 가장 좋습니다).
이 스크립트는 MCP 서버가 의도한 환경에서 실행되도록 합니다. 실행 가능하게 설정해야 합니다( chmod +x run_server.sh ).