Django Firebase MCP

A comprehensive Django app that implements Firebase Model Context Protocol (MCP) server, enabling AI agents to interact with Firebase services through a standardized protocol.

🚀 Quick Start

Get up and running in under 5 minutes with the standalone Firebase agent for testing.

Prerequisites

• Python 3.11+
• Firebase project with Admin SDK
• Git (optional)
• Redis (optional, for persistent state management)

1. Clone & Setup

git clone https://github.com/your-repo/django-firebase-mcp.git
cd django-firebase-mcp

2. Install Dependencies

pip install -r requirements.txt

3. Firebase Setup

#### Get Firebase Credentials

1. Go to Firebase Console
2. Select your project (or create a new one)
3. Navigate to Project Settings → Service Accounts
4. Click "Generate new private key"
5. Download the JSON file and save it as credentials.json in the project root

#### Enable Firebase Services

Make sure these services are enabled in your Firebase project:

• Authentication (for user management)
• Firestore Database (for document storage)
• Cloud Storage (for file uploads)

4. Environment Configuration

Create a .env file in the project root:

# Firebase Configuration
SERVICE_ACCOUNT_KEY_PATH=credentials.json
FIREBASE_STORAGE_BUCKET=your-project-id.appspot.com

# MCP Configuration
MCP_TRANSPORT=http
MCP_HOST=127.0.0.1
MCP_PORT=8001

# Django Settings
DEBUG=True
SECRET_KEY=your-secret-key-here

⚠️ Important: Replace your-project-id with your actual Firebase project ID.

5. State Management Setup

The Firebase MCP agent uses state management for conversation persistence. Choose one option:

#### Option A: Redis (Recommended for Production)

Install and run Redis on port 6379:

# Install Redis using Chocolatey
choco install redis-64

# Or download from: https://github.com/microsoftarchive/redis/releases
# Then run Redis server
redis-server

Add to your .env file:

# Redis Configuration
REDIS_URL=redis://localhost:6379
USE_REDIS=true

#### Option B: InMemorySaver (Quick Testing)

For quick testing without Redis, the agent will automatically use InMemorySaver. No additional setup required.

Add to your .env file:

# Memory-based state (no persistence)
USE_REDIS=false

Note: InMemorySaver doesn't persist conversations between restarts, while Redis maintains state across sessions.

6. Quick Test with Standalone Agent

Test your setup immediately with the standalone Firebase agent:

# Run the standalone agent
python firebase_admin_mcp/standalone_firebase_agent.py

You should see:

🔥 Firebase MCP Agent Ready!
Type 'help' for available commands, 'quit' to exit.

>

Try these commands:

> List all Firebase collections
> Check Firebase health status
> help
> quit

7. Full Django Setup (Optional)

For full Django integration:

# Apply migrations
python manage.py migrate

# Create superuser (optional)
python manage.py createsuperuser

# Run Django development server
python manage.py runserver 8001

The MCP server will be available at: http://127.0.0.1:8001/mcp/

🛠️ Management Commands

Core Commands

# Run standalone Firebase agent (quick testing)
python firebase_admin_mcp/standalone_firebase_agent.py

# Run MCP server via Django
python manage.py runserver 8001

# Run MCP server in stdio mode (for MCP clients)
python manage.py run_mcp --transport stdio

# Run MCP server in HTTP mode
python manage.py run_mcp --transport http --host 127.0.0.1 --port 8001

# Run standalone agent via Django management command
python manage.py run_standalone_agent

Testing Commands

# Test Firebase connectivity
python firebase_admin_mcp/tests/test_firebase_connection.py

# Test MCP server completeness
python firebase_admin_mcp/tests/test_mcp_complete.py

# Demo Firebase agent
python firebase_admin_mcp/tests/demo_firebase_agent.py

# Demo standalone agent
python firebase_admin_mcp/demo_standalone_agent.py

🔧 Available Tools

The MCP server provides 14 Firebase tools across three categories:

🔐 Authentication (4 tools)

• firebase_verify_token - Verify Firebase ID tokens
• firebase_create_custom_token - Create custom auth tokens
• firebase_get_user - Get user info by UID
• firebase_delete_user - Delete user accounts

📚 Firestore Database (6 tools)

• firestore_list_collections - List all collections
• firestore_create_document - Create new documents
• firestore_get_document - Retrieve documents
• firestore_update_document - Update documents
• firestore_delete_document - Delete documents
• firestore_query_collection - Query with filters

🗄️ Cloud Storage (4 tools)

• storage_list_files - List files with filtering
• storage_upload_file - Upload files
• storage_download_file - Download files
• storage_delete_file - Delete files

🧪 Quick Testing

Test Server Health

curl http://127.0.0.1:8001/mcp/

Test a Firebase Tool

curl -X POST http://127.0.0.1:8001/mcp/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "firestore_list_collections",
      "arguments": {}
    },
    "id": 1
  }'

🤖 AI Agent Integration

LangChain Example

from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# Import Firebase tools
from firebase_admin_mcp.tools.agents.firebase_mcp_client import ALL_FIREBASE_TOOLS

# Create agent with Firebase capabilities
model = ChatOpenAI(model="gpt-4")
agent = create_react_agent(
    model=model,
    tools=ALL_FIREBASE_TOOLS,
    prompt="You are a Firebase assistant with full database and storage access."
)

# Use the agent
response = agent.invoke({
    "messages": [{"role": "user", "content": "Show me all my Firestore collections"}]
})

📚 Documentation

This project includes comprehensive documentation:

• [FIREBASE_ADMIN_MCP.md](FIREBASE_ADMIN_MCP.md) - Complete technical documentation

• Detailed API reference
• All tool specifications
• Advanced configuration
• Security considerations
• Production deployment guide

• [STANDALONE_AGENT.md](STANDALONE_AGENT.md) - Standalone agent documentation
• Self-contained Firebase agent
• Complete feature overview
• Usage examples
• Integration patterns

🔧 Troubleshooting

Common Issues

Problem: Default app does not exist error Solution: Verify credentials.json path in .env file

Problem: Server won't start Solution: Check if port 8001 is available: netstat -an | findstr :8001

Problem: Firebase connection fails Solution: Verify Firebase services are enabled in console

Problem: Import errors Solution: Ensure all dependencies installed: pip install -r requirements.txt

Problem: Redis connection fails Solution: Verify Redis is running: redis-cli ping (should return "PONG")

Problem: State not persisting between sessions Solution: Check Redis configuration or switch to Redis from InMemorySaver

🎯 What's Next?

1. Explore the Standalone Agent - Perfect for quick testing and demos
2. Read the Full Documentation - See FIREBASE_ADMIN_MCP.md for complete details
3. Integrate with Your AI Agents - Use the MCP tools in your applications
4. Customize for Your Needs - Extend with additional Firebase operations

📝 Project Structure

django-firebase-mcp/
├── README.md                          # This file
├── FIREBASE_ADMIN_MCP.md             # Complete documentation
├── STANDALONE_AGENT.md               # Standalone agent guide
├── requirements.txt                   # Python dependencies
├── credentials.json                   # Firebase credentials (you create this)
├── .env                              # Environment variables (you create this)
├── manage.py                         # Django management
├── firebase_admin_mcp/               # Main MCP app
│   ├── standalone_firebase_agent.py  # Standalone agent
│   ├── tools/                        # Firebase MCP tools
│   ├── management/commands/          # Django commands
│   └── tests/                        # Test suite
└── django_firebase_mcp/             # Django project settings

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Test your changes
4. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔥 Ready to supercharge your AI agents with Firebase?

Start with the standalone agent, then explore the full documentation for advanced usage!