Firebase MCP 서버

개요

모델 컨텍스트 프로토콜(MCP) 은 LLM 클라이언트 애플리케이션이 도구를 사용하고 외부 데이터 소스에 액세스할 수 있도록 하는 개방형 프로토콜입니다. 이 MCP 서버를 통해 MCP 프로토콜을 지원하는 모든 LLM 클라이언트는 다음을 포함한 Firebase 서비스와 상호 작용할 수 있습니다.

인증 : 사용자 관리 및 검증
Firestore : 문서 데이터베이스 작업
저장 : 파일 저장 및 검색

서버는 MCP 도구를 통해 Firebase 서비스를 공개하여 Claude Desktop , Cursor , Roo Code , Cline 등의 LLM 클라이언트가 액세스할 수 있도록 하며, 인증 및 연결 관리를 처리합니다.

🔥 v1.3.0의 새로운 기능: 컬렉션 그룹 쿼리

Firebase MCP가 이제 Firestore의 하위 컬렉션(컬렉션 그룹) 쿼리를 지원합니다! 이제 상위 문서와 관계없이 동일한 이름을 가진 모든 하위 컬렉션에 대해 쿼리를 실행할 수 있습니다. 단일 쿼리로 전체 데이터베이스 계층 구조를 쉽게 검색할 수 있습니다. 문서 간 검색, 활동 피드 및 통합 대시보드에 적합합니다.

설정

Firebase MCP 서버를 설치하는 가장 쉬운 방법은 LLM 클라이언트(예: Cline)에 llms-install.md 파일을 제공하는 것입니다.

1. Firebase 구성

Firebase 콘솔 로 이동
프로젝트 설정 > 서비스 계정으로 이동합니다.
"새로운 개인 키 생성"을 클릭하세요
JSON 파일을 안전하게 저장하세요

2. 환경 변수

서버에는 다음과 같은 환경 변수가 필요합니다.

SERVICE_ACCOUNT_KEY_PATH : Firebase 서비스 계정 키 JSON 파일 경로(필수)
FIREBASE_STORAGE_BUCKET : Firebase 저장소의 버킷 이름(선택 사항)
- 제공되지 않으면 기본값은 [projectId].appspot.com 입니다.

3. MCP 서버 설치

MCP 설정 파일에 서버 구성을 추가합니다.

Claude 데스크톱: ~/Library/Application Support/Claude/claude_desktop_config.json
커서: [project root]/.cursor/mcp.json
Roo 코드(VS 코드 확장): ( ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json )
Cline(VS Code 확장): ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

MCP 서버는 npx를 통해 수동으로 또는 런타임에 설치할 수 있습니다(권장). 설치 방법에 따라 구성이 결정됩니다.

npx에 대한 구성

지엑스피1

로컬 설치를 위한 구성

{
  "firebase-mcp": {
    "command": "node",
    "args": [
      "/absolute/path/to/firebase-mcp/dist/index.js"
    ],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"
    }
  }
}

수동 설치

종속성 설치

git clone https://github.com/gannonh/firebase-mcp
cd firebase-mcp
npm install

프로젝트 빌드

npm run build

설치 테스트

모든 것이 제대로 작동하는지 확인하려면 고객에게 Please run through and test all of your Firebase MCP tools.

특징

인증 도구

auth_get_user : ID 또는 이메일로 사용자 세부 정보를 가져옵니다.
{ identifier: string // User ID or email address }

파이어스토어 도구

firestore_add_document : 컬렉션에 문서 추가
{ collection: string, data: object }
firestore_list_collections : 사용 가능한 컬렉션을 나열합니다.
{ documentPath?: string, // Optional parent document path limit?: number, // Default: 20 pageToken?: string // For pagination }
firestore_list_documents : 선택적 필터링을 사용하여 문서 나열
{ collection: string, filters?: Array<{ field: string, operator: string, value: any }>, limit?: number, pageToken?: string }
firestore_get_document : 특정 문서를 가져옵니다
{ collection: string, id: string }
firestore_update_document : 기존 문서 업데이트
{ collection: string, id: string, data: object }
firestore_delete_document : 문서 삭제
{ collection: string, id: string }
firestore_query_collection_group : 모든 하위 컬렉션에서 문서 쿼리 🆕
{ collectionId: string, // The collection ID to query across all documents filters?: Array<{ // Optional filters field: string, operator: string, // ==, !=, <, <=, >, >=, array-contains, array-contains-any, in, not-in value: any }>, orderBy?: Array<{ // Optional fields to order by field: string, direction?: 'asc' | 'desc' // Default: 'asc' }>, limit?: number, // Maximum documents to return (default: 20, max: 100) pageToken?: string // Token for pagination }

보관 도구

storage_list_files : 디렉토리의 파일 목록
{ directoryPath?: string, // Optional path, defaults to root pageSize?: number, // Number of items per page, defaults to 10 pageToken?: string // Token for pagination }
storage_get_file_info : 파일 메타데이터와 다운로드 URL을 가져옵니다.
{ filePath: string // Path to the file in storage }

개발

건물

npm run build

테스트

이 프로젝트는 테스트에 Vitest를 사용합니다. Firebase 에뮬레이터를 사용하여 프로덕션 데이터에 영향을 주지 않고 테스트를 실행할 수 있습니다.

Firebase 에뮬레이터 설치
npm install -g firebase-tools firebase init emulators
에뮬레이터 시작
firebase emulators:start
테스트 실행
npm run test:emulator

건축학

서버는 세 가지 주요 구성 요소로 구성됩니다.

src/
├── index.ts              # Server entry point
└── lib/
    └── firebase/
        ├── authClient.ts       # Authentication operations
        ├── firebaseConfig.ts   # Firebase configuration
        ├── firestoreClient.ts  # Firestore operations
        └── storageClient.ts    # Storage operations

각 클라이언트 모듈은 특정 Firebase 서비스 작업을 구현하고 이를 MCP 도구로 노출합니다.

기여하다

저장소를 포크하세요
기능 브랜치 생성
테스트를 통해 변경 사항 구현(CI 워크플로 통과를 위해 80% 이상 적용 필요)
풀 리퀘스트 제출

특허

MIT 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.

문제 해결

일반적인 문제

"지정된 버킷이 존재하지 않습니다" 오류

Firebase 저장소에 액세스하려고 할 때 이 오류가 발생하는 경우:

Firebase 프로젝트에 저장소가 활성화되어 있는지 확인하세요.
- Firebase 콘솔로 이동
- 저장소로 이동
- 아직 초기 설정을 완료하지 않았다면 완료하세요.
올바른 버킷 이름을 확인하세요
- 기본 버킷 이름은 일반적으로 [projectId].appspot.com 입니다.
- 일부 프로젝트에서는 대신 [projectId].firebasestorage.app 사용합니다.
- Firebase 콘솔의 저장소에서 버킷 이름을 찾을 수 있습니다.
FIREBASE_STORAGE_BUCKET 환경 변수를 설정합니다.
- MCP 구성에 올바른 버킷 이름을 추가하세요.
- 예: "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app"

"Firebase가 초기화되지 않았습니다" 오류

다음 오류가 표시되면:

서비스 계정 키 경로를 확인하세요
- SERVICE_ACCOUNT_KEY_PATH 의 경로가 올바르고 절대적인지 확인하세요.
- 파일이 존재하고 읽을 수 있는지 확인하세요
서비스 계정 권한 확인
- 사용 중인 Firebase 서비스에 필요한 권한이 서비스 계정에 있는지 확인하세요.
- 저장소의 경우 서비스 계정에 저장소 관리자 역할이 필요합니다.

"이 쿼리에는 복합 인덱스가 필요합니다" 오류

필터나 정렬과 함께 firestore_query_collection_group 사용할 때 이 오류가 표시되면:

오류 메시지에 제공된 URL을 따라 필요한 인덱스를 생성하세요.
인덱스가 생성되면(몇 분 정도 걸릴 수 있음) 쿼리를 다시 시도하세요.
여러 필드가 있는 복잡한 쿼리의 경우 여러 인덱스를 만들어야 할 수도 있습니다.

JSON 구문 분석 오류

잘못된 JSON에 대한 오류가 표시되는 경우:

코드에 console.log 문이 없는지 확인하세요.
- 모든 로깅은 JSON 통신을 방해하지 않도록 console.error 사용해야 합니다.
- MCP 프로토콜은 JSON 통신을 위해 stdout을 사용합니다.
요청에 구문 오류가 있는지 확인하세요
- 모든 매개변수가 올바르게 형식화되었는지 확인하세요.
- 필드 이름에 오타가 있는지 확인하세요

Firebase MCP

Integrations