lt012071/dam-firebase-mcp-server

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, and comments collections
• 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.0
• firebase-admin>=6.5.0
• python-dateutil>=2.8.2
• typing-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!

1. Create a service account in your Firebase project
2. Download the JSON credentials file
3. Copy credentials.json.example to credentials.json and fill in your actual values
4. Grant the service account the following permissions:
   • Firestore: Firebase Rules System, Cloud Datastore User
   • Storage: Storage Object Viewer

Available Tools

search_assets

Search assets in the Firestore assets collection.

Schema:

• id: string - Unique asset identifier
• title: string - Asset title
• description: string - Asset description
• category: string - Asset category
• tags: string[] - Array of tags
• uploader: string - User ID who uploaded
• uploadedAt: string - ISO8601 timestamp
• updatedAt: string - ISO8601 timestamp
• visibility: '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 identifier
• assetId: string - Parent asset ID
• version: string - Version identifier
• fileUrl: string - URL to the file
• fileName: string - Original filename
• fileType: string - MIME type
• fileSize: number - File size in bytes
• updatedAt: string - ISO8601 timestamp
• updatedBy: 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 identifier
• assetId: string - Asset being commented on
• user: string - User ID who commented
• text: string - Comment text
• createdAt: 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 path
• size: number - File size in bytes
• contentType: string - MIME type
• uploadedAt: string - ISO8601 timestamp
• downloadUrl: string - Public URL
• etag: string - ETag for versioning
• generation: 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 values
• in - 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/master branch
• 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

1. Credentials not found: Ensure the service account JSON file path is correct
2. Permission denied: Verify the service account has the required Firebase permissions
3. Connection issues: Check network connectivity and Firebase project settings
4. 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.