MCP Firebase 서버

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 파일입니다.

설정

복제/다운로드: 로컬 디렉토리에 서버 파일( 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 통한 stdio 전송): 서버 실행을 간소화하기 위해 run_server.sh 스크립트가 제공됩니다. 이 스크립트는 Python 스크립트를 실행하기 전에 가상 환경( venv 라는 이름이 지정되어 있고 프로젝트 루트에 있는 경우)을 활성화합니다.먼저 스크립트를 실행 가능하게 만듭니다.
chmod +x run_server.sh
그런 다음 스크립트를 사용하여 서버를 실행합니다.
./run_server.sh
이는 일반적으로 MCP 클라이언트가 서버를 실행하기 위해 구성되는 방식입니다(아래 "Claude와 함께 사용" 섹션 참조).
**개발 및 검사를 위한 MCP CLI 사용( mcp dev ): mcp CLI( 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 등)의 특정 구성 메커니즘에 맞게 이 예시를 조정해야 합니다.

{
  "mcpServers": {
    "my_firebase_mcp_connector": { // A unique name you assign to this server instance in the client's config
      "command": "/full/path/to/your/mc-firebase-server/run_server.sh", // IMPORTANT: Use the absolute path to the script
      "args": [], // Typically empty if run_server.sh handles everything
      // "cwd": "/full/path/to/your/mc-firebase-server/", // Usually not needed if run_server.sh cds to its own dir
      "env": { 
        "SERVICE_ACCOUNT_KEY_PATH": "/Users/davidloor/projects/firebase/examcoachai/examcoachai-firebase-adminsdk-qwhk9-5c7a5b82e2.json",
        "FIREBASE_STORAGE_BUCKET": "examcoachai.appspot.com" // Example bucket name, adjust to your actual bucket
      }
    }
  }
}

구성의 핵심 사항:

"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 ).

MCP Firebase Server

Integrations