Django Firebase MCP

# 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 ```bash git clone https://github.com/your-repo/django-firebase-mcp.git cd django-firebase-mcp ``` ### 2. Install Dependencies ```bash pip install -r requirements.txt ``` ### 3. Firebase Setup #### Get Firebase Credentials 1. Go to [Firebase Console](https://console.firebase.google.com/) 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: ```env # 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: ```powershell # 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: ```env # 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: ```env # 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: ```bash # 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: ```bash # 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 ```bash # 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 ```bash # 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 ```bash curl http://127.0.0.1:8001/mcp/ ``` ### Test a Firebase Tool ```bash 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 ```python 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!