파이어베이스 MCP

프로젝트 로고

개요

Firebase MCP를 사용하면 AI 어시스턴트가 다음을 포함한 Firebase 서비스와 직접 작업할 수 있습니다.

Firestore : 문서 데이터베이스 작업
저장 : 강력한 업로드 기능을 갖춘 파일 관리
인증 : 사용자 관리 및 검증

이 서버는 Claude Desktop , Augment Code , VS Code , Cursor 와 같은 MCP 클라이언트 애플리케이션과 함께 작동합니다.

⚠️ 알려진 문제 : firestore_list_collections 도구가 클라이언트 로그에 Zod 유효성 검사 오류를 반환할 수 있습니다. 이는 MCP SDK의 잘못된 유효성 검사 오류로, 조사 결과 응답에 부울 값이 없는 것으로 확인되었습니다. 오류 메시지에도 불구하고 쿼리는 여전히 정상적으로 작동하며 올바른 컬렉션 데이터를 반환합니다. 이는 기능에 영향을 미치지 않는 로그 수준 오류입니다.

⚡ 빠른 시작

필수 조건

서비스 계정 자격 증명이 있는 Firebase 프로젝트
Node.js 환경

1. MCP 서버 설치

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

Claude 데스크톱: ~/Library/Application Support/Claude/claude_desktop_config.json
확장: ~/Library/Application Support/Code/User/settings.json
커서: [project root]/.cursor/mcp.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"
    }
  }
}

2. 설치 테스트

AI 클라이언트에게 "모든 Firebase MCP 도구를 테스트해 주세요."라고 요청하세요.

🛠️ 설정 및 구성

1. Firebase 구성

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

2. 환경 변수

필수의

SERVICE_ACCOUNT_KEY_PATH : Firebase 서비스 계정 키 JSON 경로(필수)

선택 과목

FIREBASE_STORAGE_BUCKET : Firebase 저장소의 버킷 이름(기본값은 [projectId].appspot.com )
MCP_TRANSPORT : 사용할 전송 유형( stdio 또는 http )(기본값은 stdio )
MCP_HTTP_PORT : HTTP 전송을 위한 포트(기본값은 3000 )
MCP_HTTP_HOST : HTTP 전송을 위한 호스트(기본값은 localhost )
MCP_HTTP_PATH : HTTP 전송 경로(기본값은 /mcp )
DEBUG_LOG_FILE : 파일 로깅을 활성화합니다.
- ~/.firebase-mcp/debug.log 에 기록하려면 true 로 설정합니다.
- 사용자 정의 위치에 기록할 파일 경로를 설정합니다.

3. 클라이언트 통합

클로드 데스크탑

편집: ~/Library/Application Support/Claude/claude_desktop_config.json

VS 코드 / 증강

편집: ~/Library/Application Support/Code/User/settings.json

커서

편집: [project root]/.cursor/mcp.json

📚 API 참조

파이어스토어 도구

도구	설명	필수 매개변수
`firestore_add_document`	컬렉션에 문서 추가	`collection` , `data`
`firestore_list_documents`	필터링을 사용하여 문서 나열	`collection`
`firestore_get_document`	특정 문서를 받으세요	`collection` , `id`
`firestore_update_document`	기존 문서 업데이트	`collection` , `id` , `data`
`firestore_delete_document`	문서 삭제	`collection` , `id`
`firestore_list_collections`	루트 컬렉션 나열	없음
`firestore_query_collection_group`	하위 컬렉션에 대한 쿼리	`collectionId`

보관 도구

도구	설명	필수 매개변수
`storage_list_files`	디렉토리의 파일 나열	없음(선택 사항: `directoryPath` )
`storage_get_file_info`	파일 메타데이터 및 URL 가져오기	`filePath`
`storage_upload`	콘텐츠에서 파일 업로드	`filePath` , `content`
`storage_upload_from_url`	URL에서 파일 업로드	`filePath` , `url`

인증 도구

도구	설명	필수 매개변수
`auth_get_user`	ID 또는 이메일로 사용자 가져오기	`identifier`

💻 개발자 가이드

설치 및 구축

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

테스트 실행

먼저 Firebase 에뮬레이터를 설치하고 시작합니다.

npm install -g firebase-tools
firebase init emulators
firebase emulators:start

그런 다음 테스트를 실행합니다.

# Run tests with emulator
npm run test:emulator

# Run tests with coverage
npm run test:coverage:emulator

프로젝트 구조

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

🌐 HTTP 전송

Firebase MCP는 이제 기본 stdio 전송 외에도 HTTP 전송을 지원합니다. 이를 통해 서버를 여러 클라이언트에서 액세스할 수 있는 독립형 HTTP 서비스로 실행할 수 있습니다.

HTTP 전송으로 실행

HTTP 전송으로 서버를 실행하려면:

# Using environment variables
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.js

# Or with npx
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npx @gannonh/firebase-mcp

HTTP에 대한 클라이언트 구성

HTTP 전송을 사용하는 경우 MCP 클라이언트를 구성하여 HTTP 엔드포인트에 연결하세요.

{
  "firebase-mcp": {
    "url": "http://localhost:3000/mcp"
  }
}

세션 관리

HTTP 전송은 세션 관리를 지원하여 여러 클라이언트가 동일한 서버 인스턴스에 연결할 수 있도록 합니다. 각 클라이언트는 요청 간 상태를 유지하는 데 사용되는 고유한 세션 ID를 받습니다.

🔍 문제 해결

일반적인 문제

저장 버킷을 찾을 수 없습니다

"지정된 버킷이 존재하지 않습니다" 오류가 나타나는 경우:

Firebase 콘솔 → 저장소에서 버킷 이름을 확인하세요.
FIREBASE_STORAGE_BUCKET 환경 변수에 올바른 버킷 이름을 설정하세요.

Firebase 초기화에 실패했습니다

"Firebase가 초기화되지 않았습니다" 오류가 표시되는 경우:

서비스 계정 키 경로가 올바르고 절대적인지 확인하세요.
서비스 계정에 Firebase 서비스에 대한 적절한 권한이 있는지 확인하세요.

복합 지수 필요

"이 쿼리에는 복합 인덱스가 필요합니다" 오류가 발생하는 경우:

오류 메시지에서 제공된 URL을 찾으세요.
Firebase 콘솔에서 필요한 인덱스를 생성하려면 링크를 따르세요.
인덱스가 생성된 후 쿼리를 다시 시도하세요(몇 분 정도 걸릴 수 있음)

`firestore_list_collections` 에서 Zod 유효성 검사 오류 발생

firestore_list_collections 도구를 사용할 때 "예상된 개체이지만 부울 값을 받았습니다"라는 메시지와 함께 Zod 검증 오류가 표시되는 경우:

⚠️ 알려진 문제 : firestore_list_collections 도구가 클라이언트 로그에 Zod 유효성 검사 오류를 반환할 수 있습니다. 이는 MCP SDK의 잘못된 유효성 검사 오류로, 조사 결과 응답에 부울 값이 없는 것으로 확인되었습니다. 오류 메시지에도 불구하고 쿼리는 여전히 정상적으로 작동하며 올바른 컬렉션 데이터를 반환합니다. 이는 기능에 영향을 미치지 않는 로그 수준 오류입니다.

디버깅

파일 로깅 활성화

문제 진단에 도움이 되도록 파일 로깅을 활성화할 수 있습니다.

# Log to default location (~/.firebase-mcp/debug.log)
DEBUG_LOG_FILE=true npx @gannonh/firebase-mcp

# Log to a custom location
DEBUG_LOG_FILE=/path/to/custom/debug.log npx @gannonh/firebase-mcp

MCP 클라이언트 구성에서 로깅을 활성화할 수도 있습니다.

{
  "firebase-mcp": {
    "command": "npx",
    "args": ["-y", "@gannonh/firebase-mcp"],
    "env": {
      "SERVICE_ACCOUNT_KEY_PATH": "/path/to/serviceAccountKey.json",
      "FIREBASE_STORAGE_BUCKET": "your-project-id.firebasestorage.app",
      "DEBUG_LOG_FILE": "true"
    }
  }
}

실시간 로그 보기

실시간으로 로그를 보려면:

# Using tail to follow the log file
tail -f ~/.firebase-mcp/debug.log

# Using a split terminal to capture stderr
npm start 2>&1 | tee logs.txt

MCP Inspector 사용

MCP Inspector는 대화형 디버깅을 제공합니다.

# Install MCP Inspector
npm install -g @mcp/inspector

# Connect to your MCP server
mcp-inspector --connect stdio --command "node ./dist/index.js"

📋 응답 형식

저장소 업로드 응답 예

{
  "name": "reports/quarterly.pdf",
  "size": "1024000",
  "contentType": "application/pdf",
  "updated": "2025-04-11T15:37:10.290Z",
  "downloadUrl": "https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media",
  "bucket": "your-project.appspot.com"
}

사용자에게 다음과 같이 표시됩니다.

## File Successfully Uploaded! 📁

Your file has been uploaded to Firebase Storage:

**File Details:**
- **Name:** reports/quarterly.pdf
- **Size:** 1024000 bytes
- **Type:** application/pdf
- **Last Updated:** April 11, 2025 at 15:37:10 UTC

**[Click here to download your file](https://storage.googleapis.com/bucket/reports/quarterly.pdf?alt=media)**

🤝 기여하기

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

📄 라이센스

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

🔗 관련 자료

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

View all tools

Firebase MCP 서버는 Firebase 인증, Firestore, Firebase 저장소를 비롯한 Firebase 서비스와 상호 작용하기 위한 표준화된 인터페이스를 제공합니다.

Related Resources

Reddit Discussion about this server

Related MCP Servers

Firebase MCP Server
gemini-dk
A
security
F
license
A
quality
A server providing a unified interface to interact with Firebase services, including Authentication, Firestore, and Storage.
Last updated -
9
7
TypeScript
FireConfigMCP
IdanAizikNissim
-
security
F
license
-
quality
An MCP server that provides access to Firebase Remote Config, allowing clients to interact with and manage Firebase remote configuration settings through the Model Context Protocol.
Last updated -
TypeScript
Firebase App Distribution API MCP Server
ag2-mcp-servers
-
security
F
license
-
quality
Auto-generated MCP server that enables interaction with the Firebase App Distribution API, allowing users to manage distribution of pre-release app builds to testers through natural language commands.
Last updated -
Python
Firebase Management MCP Server
ag2-mcp-servers
-
security
F
license
-
quality
An MCP Server providing access to Google's Firebase API, allowing natural language interaction with Firebase services and resources.
Last updated -
Python

View all related MCP servers