{"id":26641104,"url":"https://github.com/hyperb1iss/django-mcp","last_synced_at":"2026-05-09T14:41:44.007Z","repository":{"id":283774507,"uuid":"952365623","full_name":"hyperb1iss/django-mcp","owner":"hyperb1iss","description":" Connect Django apps to AI assistants with Model Context Protocol. Simple decorators expose models, admin functions, and custom tools to Claude and other AI assistants.","archived":false,"fork":false,"pushed_at":"2025-03-22T04:23:35.000Z","size":188,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-22T05:21:38.206Z","etag":null,"topics":["ai-assistants","django","integration","mcp","model-context-protocol","python"],"latest_commit_sha":null,"homepage":"https://hyperbliss.tech","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperb1iss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"hyperb1iss","ko_fi":"hyperb1iss"}},"created_at":"2025-03-21T06:54:00.000Z","updated_at":"2025-03-22T04:23:39.000Z","dependencies_parsed_at":"2025-03-22T05:22:00.061Z","dependency_job_id":"88c47caf-e539-456f-85de-ea8c95e0c22e","html_url":"https://github.com/hyperb1iss/django-mcp","commit_stats":null,"previous_names":["hyperb1iss/django-mcp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fdjango-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fdjango-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fdjango-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperb1iss%2Fdjango-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperb1iss","download_url":"https://codeload.github.com/hyperb1iss/django-mcp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245325220,"owners_count":20596818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistants","django","integration","mcp","model-context-protocol","python"],"created_at":"2025-03-24T18:19:45.447Z","updated_at":"2026-05-09T14:41:43.966Z","avatar_url":"https://github.com/hyperb1iss.png","language":"Python","funding_links":["https://github.com/sponsors/hyperb1iss","https://ko-fi.com/hyperb1iss"],"categories":[],"sub_categories":[],"readme":"# ✨ Django-MCP 🔮\n\n\u003cdiv align=\"center\"\u003e\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-9D00FF.svg?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://www.python.org/downloads/)\n[![Django 4.0+](https://img.shields.io/badge/django-4.0+-FF00FF.svg?style=for-the-badge\u0026logo=django\u0026logoColor=white)](https://www.djangoproject.com/)\n[![License](https://img.shields.io/badge/license-Apache--2.0-FF00FF.svg?style=for-the-badge\u0026logo=apache\u0026logoColor=white)](LICENSE)\n[![Status](https://img.shields.io/badge/status-alpha-FF3366.svg?style=for-the-badge\u0026logo=statuspage\u0026logoColor=white)](docs/plan.md)\n[![Style](https://img.shields.io/badge/code_style-ruff-00FFFF.svg?style=for-the-badge\u0026logo=ruff\u0026logoColor=white)](https://github.com/astral-sh/ruff)\n[![Types](https://img.shields.io/badge/type_checker-mypy-00FF88.svg?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://mypy-lang.org/)\n\n**Supercharge your Django apps with AI assistant capabilities**\n\n\u003c/div\u003e\n\nDjango-MCP bridges the gap between Django applications and AI assistants by implementing the [Model Context Protocol (MCP)](https://docs.anthropic.com/claude/docs/model-context-protocol-mcp). With a few simple decorators, you can expose your app's data and functionality to AI assistants, creating richer, more capable AI interactions.\n\nWant AI to help users explore your data, perform admin tasks, or create content? Django-MCP makes it magical! ✨💫🧙‍♀️\n\n## 🌟 Features\n\n- 🔮 **Seamless Integration** - Add MCP to your Django project with minimal configuration\n- 🧩 **Decorator-Based API** - Intuitive decorators to expose functions, models, and views\n- 📊 **Django ORM Integration** - First-class support for Django models and querysets\n- 🛡️ **Admin Integration** - Expose admin actions and panels to AI assistants\n- 🌐 **DRF Compatibility** - Works with Django REST Framework viewsets and serializers\n- 🔍 **Auto-Discovery** - Automatically finds and registers MCP components in your apps\n- 🚀 **ASGI Support** - Built-in ASGI server for SSE-based MCP communication\n- ⚙️ **Flexible Configuration** - Configure through familiar Django settings\n- 🔒 **Security-Focused** - Safe by default with clear permission controls\n- 📝 **Contextual Awareness** - MCP server understands Django request context\n\n## 🚀 Installation\n\n```bash\n# Install with pip\npip install django-mcp\n\n# Or with UV\nuv add django-mcp\n```\n\n## ⚡ Quick Start\n\n### 1. Add to INSTALLED_APPS\n\n```python\n# settings.py\nINSTALLED_APPS = [\n    # ... your other apps ...\n    'django_mcp',\n]\n\n# MCP Configuration (optional)\nDJANGO_MCP_SERVER_NAME = \"My Awesome Django App\"\nDJANGO_MCP_INSTRUCTIONS = \"This server provides access to my Django app.\"\n```\n\n### 2. Update your ASGI configuration\n\n```python\n# asgi.py\nfrom django_mcp.asgi import get_asgi_application\n\napplication = get_asgi_application()\n```\n\n### 3. Include MCP URLs\n\n```python\n# urls.py\nfrom django.urls import path, include\n\nurlpatterns = [\n    # ... your other URLs ...\n    path('', include('django_mcp.urls')),\n]\n```\n\n### 4. Create your first MCP tool\n\n```python\n# myapp/mcp_tools.py - automatically discovered!\nfrom django_mcp.decorators import mcp_tool\nfrom django_mcp.context import Context\nfrom myapp.models import Product\n\n@mcp_tool()\ndef search_products(context: Context, query: str) -\u003e list:\n    \"\"\"Search for products by name\"\"\"\n    products = Product.objects.filter(name__icontains=query)[:10]\n    return [\n        {\n            \"id\": p.id,\n            \"name\": p.name,\n            \"price\": str(p.price),\n            \"description\": p.description,\n        }\n        for p in products\n    ]\n```\n\n### 5. Expose a Django model\n\n```python\n# myapp/models.py\nfrom django.db import models\nfrom django_mcp.decorators import mcp_model_tool, mcp_model_resource\n\nclass Product(models.Model):\n    name = models.CharField(max_length=100)\n    price = models.DecimalField(max_digits=10, decimal_places=2)\n    description = models.TextField()\n\n    def __str__(self):\n        return self.name\n\n# Expose CRUD operations for Product model\n@mcp_model_tool(Product)\ndef product_tools():\n    pass\n\n# Expose Product instances as resources\n@mcp_model_resource(Product)\ndef product_resource():\n    pass\n```\n\n### 6. Connect your AI assistant\n\nPoint your MCP-compatible AI assistant (like Claude) to:\n\n```\nhttp://yourdomain.com/mcp/\n```\n\nNow your AI assistant can use your Django app's functionality!\n\n## 🧙‍♀️ Using with AI Assistants\n\n1. Start your Django server with Django-MCP installed\n2. Connect your AI assistant using the MCP protocol URI\n3. The AI can now invoke your tools and access your resources!\n\nExample conversation with an AI:\n\n```\nUser: \"How many products do we have in our database priced under $20?\"\n\nAI: *uses the search_products tool to find this information*\n\"I found 15 products under $20. The most popular ones are Product A ($15.99),\nProduct B ($19.50), and Product C ($12.75). Would you like to see more details\nabout any of these products?\"\n```\n\n## 💫 Examples\n\n### Admin Integration\n\n```python\nfrom django_mcp.admin_tools import register_admin_tools\nfrom myapp.admin import ProductAdmin\nfrom myapp.models import Product\n\n# Register all admin actions for Product\nregister_admin_tools(ProductAdmin, Product)\n```\n\n### DRF Integration\n\n```python\nfrom django_mcp.drf_tools import register_drf_viewset\nfrom myapp.api.viewsets import ProductViewSet\n\n# Expose all viewset actions as tools\nregister_drf_viewset(ProductViewSet)\n```\n\n### Creating Resources\n\n```python\nfrom django_mcp.decorators import mcp_resource\nfrom myapp.models import Category\n\n@mcp_resource(\"category://{slug}\")\ndef get_category(slug: str) -\u003e str:\n    \"\"\"Get information about a product category\"\"\"\n    category = Category.objects.get(slug=slug)\n    products = category.product_set.all()\n\n    return f\"\"\"# Category: {category.name}\n\n{category.description}\n\n## Products in this category\n\n{', '.join(p.name for p in products[:10])}\n\nTotal products: {products.count()}\n\"\"\"\n```\n\n## 🛠️ Advanced Configuration\n\nDjango-MCP offers advanced configuration options through Django settings:\n\n```python\n# settings.py\n\n# Core settings\nDJANGO_MCP_SERVER_NAME = \"My Django App\"\nDJANGO_MCP_URL_PREFIX = \"mcp\"  # URL prefix for MCP endpoints\nDJANGO_MCP_INSTRUCTIONS = \"This server provides access to my Django app.\"\nDJANGO_MCP_DEPENDENCIES = []  # MCP dependencies\n\n# Discovery settings\nDJANGO_MCP_AUTO_DISCOVER = True  # Auto-discover MCP components\nDJANGO_MCP_EXPOSE_MODELS = True  # Auto-expose Django models\nDJANGO_MCP_EXPOSE_ADMIN = True  # Auto-expose Django admin\nDJANGO_MCP_EXPOSE_DRF = True  # Auto-expose DRF ViewSets\n\n# Security settings\nDJANGO_MCP_ALLOWED_ORIGINS = []  # CORS allowed origins for SSE endpoint\n```\n\n## 📊 Dashboard\n\nDjango-MCP includes a built-in dashboard at `/mcp/dashboard/` that shows all registered tools, resources, and prompts.\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests (`pytest`)\n5. Commit your changes (`git commit -m 'Add some amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the Apache License 2.0 - see the LICENSE file for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nCreated by [Stefanie Jane 🌠](https://github.com/hyperb1iss)\n\nIf you find Django-MCP useful, [buy me a Monster Ultra Violet ⚡️](https://ko-fi.com/hyperb1iss)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperb1iss%2Fdjango-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperb1iss%2Fdjango-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperb1iss%2Fdjango-mcp/lists"}