Firebase MCP Server
A Model Context Protocol (MCP) server implementation for accessing Firebase Firestore and Storage, built with Python and FastMCP.
Overview
This MCP server provides secure access to Firebase Firestore collections and Storage buckets through MCP-compliant tools. It's designed specifically for a Digital Asset Management (DAM) system with predefined collections and access patterns.
Features
- MCP Protocol Compliance: Fully compliant with the official MCP specification
- Firestore Access: Query
assets,versions, andcommentscollections - Storage Access: Search files in the Firebase Storage bucket
- Flexible Filtering: Support for various filter operators including date ranges
- Dual Transport: Support for both stdio and HTTP transports
- Docker Support: Containerized deployment with Docker
- Security: Service account-based authentication with restricted access
Installation
Prerequisites
- Python 3.11 or higher
- Firebase project with Firestore and Storage enabled
- Google Cloud service account with appropriate permissions
Dependencies
pip install -r requirements.txt
Required Python Packages
fastmcp>=0.1.0firebase-admin>=6.5.0python-dateutil>=2.8.2typing-extensions>=4.9.0
Usage
Command Line
# Run with stdio transport (for MCP clients)
python main.py --google-credentials /path/to/service-account.json --transport stdio
# Run with HTTP transport (for web access)
python main.py --google-credentials /path/to/service-account.json --transport http --host 0.0.0.0 --port 8000
# Enable debug logging
python main.py --google-credentials /path/to/service-account.json --debug
Docker
# Build the image
docker build -t firebase-mcp-server .
# Run with docker-compose
docker-compose up -d
# Run manually
docker run -p 8000:8000 -v /path/to/credentials.json:/app/credentials.json firebase-mcp-server
Configuration
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"firebase-dam": {
"command": "python",
"args": [
"/path/to/mcp-server/main.py",
"--google-credentials",
"/path/to/your/service-account-credentials.json",
"--transport",
"stdio"
],
"env": {
"PYTHONPATH": "/path/to/mcp-server"
}
}
}
}
Service Account Setup
⚠️ SECURITY WARNING: Never commit credentials files to version control!
- Create a service account in your Firebase project
- Download the JSON credentials file
- Copy
credentials.json.exampletocredentials.jsonand fill in your actual values - Grant the service account the following permissions:
- Firestore:
Firebase Rules System,Cloud Datastore User - Storage:
Storage Object Viewer
- Firestore:
Available Tools
search_assets
Search assets in the Firestore assets collection.
Schema:
id: string - Unique asset identifiertitle: string - Asset titledescription: string - Asset descriptioncategory: string - Asset categorytags: string[] - Array of tagsuploader: string - User ID who uploadeduploadedAt: string - ISO8601 timestampupdatedAt: string - ISO8601 timestampvisibility: 'public' | 'private'latestVersionId: string (optional)
Example:
{
"category": "image",
"tags": ["banner"],
"visibility": "public",
"uploadedAt": ">=2024-06-01"
}
search_versions
Search versions in the Firestore versions collection.
Schema:
id: string - Unique version identifierassetId: string - Parent asset IDversion: string - Version identifierfileUrl: string - URL to the filefileName: string - Original filenamefileType: string - MIME typefileSize: number - File size in bytesupdatedAt: string - ISO8601 timestampupdatedBy: string - User ID who updated
Example:
{
"assetId": "asset123",
"fileType": "image/png",
"updatedAt": ">=2024-06-01"
}
search_comments
Search comments in the Firestore comments collection.
Schema:
id: string - Unique comment identifierassetId: string - Asset being commented onuser: string - User ID who commentedtext: string - Comment textcreatedAt: string - ISO8601 timestamp
Example:
{
"assetId": "asset123",
"user": "user456",
"createdAt": ">=2024-06-01"
}
search_asset_files
Search files in the Firebase Storage bucket.
Returns:
name: string - Full file pathsize: number - File size in bytescontentType: string - MIME typeuploadedAt: string - ISO8601 timestampdownloadUrl: string - Public URLetag: string - ETag for versioninggeneration: number - File generation
Example:
{
"prefix": "assets/",
"contentType": "image/png",
"uploadedAt": ">=2024-06-01"
}
Filter Operators
==- Equality (default)>=- Greater than or equal (for dates)<=- Less than or equal (for dates)array_contains_any- Array contains any of the valuesin- Value is in the provided array
Architecture
src/
├── mcp_server_firebase/
│ ├── __init__.py
│ ├── server.py # FastMCP server with tools
│ └── firebase_client.py # Firebase client wrapper
├── main.py # Entry point
├── requirements.txt # Python dependencies
├── Dockerfile # Container configuration
├── docker-compose.yml # Docker Compose setup
└── examples/ # Configuration examples
Security Notes
- Collections and bucket names are hardcoded in the source code
- Access is restricted to read-only operations
- Service account credentials are required for authentication
- No sensitive data is logged or exposed
Development
Setup Development Environment
# Clone the repository
git clone https://github.com/lt012071/dam-firebase-mcp-server.git
cd dam-firebase-mcp-server
# Install development dependencies
make install-dev
# Or manually:
pip install -r requirements.txt
pip install -r requirements-dev.txt
pre-commit install
Running Tests
# Run all unit tests (recommended for development)
make test
# or: pytest tests/unit/ -v -m "unit"
# Run integration tests
make test-integration
# or: pytest tests/integration/ -v -m "integration and not slow"
# Run all tests with coverage
make test-all
# or: pytest tests/ --cov=src --cov-report=html
# Run slow tests (only on CI)
make test-slow
# or: pytest tests/integration/ -v -m "slow"
# Run tests in watch mode (for development)
make test-watch
Code Quality
# Format code
make format
# or: black src/ tests/ && isort src/ tests/
# Run linting
make lint
# or: flake8 src/ tests/
# Type checking
make type-check
# or: mypy src/ --ignore-missing-imports
# Security scanning
make security
# or: bandit -r src/ && safety check
# Run all quality checks
make quality
# Run pre-commit hooks
make pre-commit
Test Coverage
# Generate HTML coverage report
make coverage-html
# Open htmlcov/index.html in browser
# Generate XML coverage report (for CI)
make coverage-xml
Docker Testing
# Build and test Docker image
make docker-build
make docker-test
# Run with docker-compose
make docker-compose-up
Test Categories
- Unit Tests (
tests/unit/): Fast tests with mocked dependencies - Integration Tests (
tests/integration/): Tests MCP protocol communication - Slow Tests (marked with
@pytest.mark.slow): Performance and stress tests
Writing Tests
# Unit test example
@pytest.mark.unit
def test_firebase_client_init(test_credentials_file):
client = FirebaseClient(test_credentials_file)
assert client.credentials_path == test_credentials_file
# Integration test example
@pytest.mark.integration
@pytest.mark.asyncio
async def test_mcp_tool_via_protocol(test_credentials_file):
# Test actual MCP communication
pass
# Slow test example
@pytest.mark.slow
@pytest.mark.integration
async def test_large_dataset_handling():
# Performance test with large datasets
pass
Continuous Integration
Tests run automatically on:
- Push to
main/masterbranch - Pull request creation
- Multiple Python versions (3.10, 3.11, 3.12)
The CI pipeline includes:
- Unit tests with coverage
- Integration tests
- Code quality checks (linting, typing, security)
- Docker build verification
Troubleshooting
Common Issues
- Credentials not found: Ensure the service account JSON file path is correct
- Permission denied: Verify the service account has the required Firebase permissions
- Connection issues: Check network connectivity and Firebase project settings
- Import errors: Ensure all dependencies are installed correctly
Debug Mode
Enable debug logging to see detailed operation logs:
python main.py --google-credentials /path/to/credentials.json --debug
License
This project is licensed under the MIT License.