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
- Go to Firebase Console
- Select your project (or create a new one)
- Navigate to Project Settings → Service Accounts
- Click "Generate new private key"
- Download the JSON file and save it as
credentials.jsonin 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 tokensfirebase_create_custom_token- Create custom auth tokensfirebase_get_user- Get user info by UIDfirebase_delete_user- Delete user accounts
📚 Firestore Database (6 tools)
firestore_list_collections- List all collectionsfirestore_create_document- Create new documentsfirestore_get_document- Retrieve documentsfirestore_update_document- Update documentsfirestore_delete_document- Delete documentsfirestore_query_collection- Query with filters
🗄️ Cloud Storage (4 tools)
storage_list_files- List files with filteringstorage_upload_file- Upload filesstorage_download_file- Download filesstorage_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 - Complete technical documentation
- Detailed API reference
- All tool specifications
- Advanced configuration
- Security considerations
- Production deployment guide
-
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?
- Explore the Standalone Agent - Perfect for quick testing and demos
- Read the Full Documentation - See FIREBASE_ADMIN_MCP.md for complete details
- Integrate with Your AI Agents - Use the MCP tools in your applications
- 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
- Fork the repository
- Create a feature branch
- Test your changes
- 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!