django-telescope
Advanced tools
A Model Context Protocol (MCP) server for Django applications, inspired by Laravel Boost
A Model Context Protocol (MCP) server for Django applications, inspired by Laravel Boost. This server exposes Django project information through MCP tools, enabling AI assistants to better understand and interact with Django codebases.
Project Discovery: List models, URLs, and management commands
Django Telescope MCP server providing Django project introspection through AI assistants (Example using OpenCode)
# Using uv (recommended)
uv pip install django-telescope
# Or with pip
pip install django-telescope
If you want to contribute or run the latest development version:
# Clone the repository
git clone https://github.com/vinta/django-telescope.git
cd django-telescope
# Install uv if you haven't already
# On macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Install dependencies (creates virtual environment automatically)
uv sync --dev
# Verify installation
uv run django-telescope --help
The server requires access to your Django project's settings:
# Set the Django settings module
export DJANGO_SETTINGS_MODULE=myproject.settings
django-telescope
# Or specify settings directly
django-telescope --settings myproject.settings
# Run with SSE transport (default is stdio)
django-telescope --settings myproject.settings --transport sse
Add to your Claude Desktop configuration:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/claude/claude_desktop_config.json{
"mcpServers": {
"django": {
"command": "django-telescope",
"args": ["--settings", "myproject.settings"],
"env": {
"DJANGO_SETTINGS_MODULE": "myproject.settings",
"PYTHONPATH": "/path/to/your/django/project"
}
}
}
}
Note: Make sure to replace /path/to/your/django/project with the actual path to your Django project root directory.
.mcp.json in your Django project root:{
"mcpServers": {
"django-telescope": {
"command": "uv",
"args": ["run", "django-telescope", "--settings", "myproject.settings"],
"env": {
"DJANGO_SETTINGS_MODULE": "myproject.settings"
}
}
}
}
OpenAI ChatGPT Desktop supports MCP servers. Add to your configuration file:
~/Library/Application Support/OpenAI/ChatGPT/config.json%APPDATA%\OpenAI\ChatGPT\config.json{
"mcpServers": {
"django": {
"command": "django-telescope",
"args": ["--settings", "myproject.settings"],
"env": {
"DJANGO_SETTINGS_MODULE": "myproject.settings"
}
}
}
}
{
"django": {
"command": "django-telescope",
"args": ["--settings", "myproject.settings"],
"env": {
"DJANGO_SETTINGS_MODULE": "myproject.settings"
}
}
}
Add to your Zed MCP configuration (~/.config/zed/mcp.json):
{
"servers": {
"django": {
"command": "django-telescope",
"args": ["--settings", "myproject.settings"],
"env": {
"DJANGO_SETTINGS_MODULE": "myproject.settings"
}
}
}
}
For any MCP-compatible client, you can run the server manually:
# Standard I/O transport (default)
django-telescope --settings myproject.settings
# Server-Sent Events transport
django-telescope --settings myproject.settings --transport sse
application_infoGet Django and Python versions, installed apps, middleware, database engine, and debug mode status.
get_settingRetrieve any Django setting using dot notation (e.g., DATABASES.default.ENGINE).
list_modelsList all Django models with fields, types, max_length, null/blank status, and relationships.
list_urlsShow all URL patterns with names, patterns, and view handlers (including nested includes).
database_schemaGet complete database schema including tables, columns, types, indexes, and foreign keys.
list_migrationsView all migrations per app with their applied/unapplied status.
list_management_commandsList all available manage.py commands with their source apps.
get_absolute_urlGet the absolute URL for a specific model instance. Requires the model to have a get_absolute_url() method defined.
Arguments:
app_label: The Django app label (e.g., "blog")model_name: The model name (e.g., "Post")pk: The primary key of the instancereverse_urlReverse a named URL pattern to get its actual URL path. Supports both positional args and keyword arguments.
Arguments:
url_name: The URL pattern name (e.g., "post_detail", "admin:index")args: Optional list of positional argumentskwargs: Optional dict of keyword argumentsread_recent_logsRead recent log entries with optional filtering by log level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
MCP prompts provide reusable message templates to help guide interactions with AI assistants.
search_django_docsGenerate a formatted prompt to help search for specific topics in Django documentation.
Arguments:
topic: The Django topic or feature to search for (e.g., "models", "queryset", "migrations", "authentication")Returns: A formatted prompt that includes:
Example topics:
This prompt automatically adapts to your Django version (e.g., 5.2, 4.2) to ensure documentation compatibility.
Once configured, you can ask your AI assistant questions like:
Using Tools:
Using Prompts:
The project includes a comprehensive test suite and a fixture Django project for development:
# Test the MCP server with the fixture project
uv run python test_server.py
# Run the MCP server with the test project
export PYTHONPATH="${PYTHONPATH}:./fixtures/testproject"
uv run django-telescope --settings testproject.settings
# Run linter
uv run ruff check .
# Auto-fix linting issues
uv run ruff check --fix .
# Format code
uv run ruff format .
The fixtures/testproject/ directory contains a complete Django application for testing all MCP tools. See fixtures/README.md for details about the test project structure.
Make sure you've set the DJANGO_SETTINGS_MODULE environment variable or used the --settings flag:
export DJANGO_SETTINGS_MODULE=myproject.settings
django-telescope
If Django can't find your project modules, add your project directory to PYTHONPATH:
export PYTHONPATH="${PYTHONPATH}:/path/to/your/project"
django-telescope --settings myproject.settings
Or in your MCP client configuration:
{
"env": {
"PYTHONPATH": "/path/to/your/project",
"DJANGO_SETTINGS_MODULE": "myproject.settings"
}
}
django-telescope command is accessible in your PATHdjango-telescope --settings myproject.settings
Ensure your Django database is properly configured and accessible. The MCP server needs the same database access as your Django application.
MIT License - see LICENSE file for details.
This project is inspired by Laravel Boost, which provides similar MCP functionality for Laravel applications.
We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or bug reports, your help is appreciated.
git clone https://github.com/YOUR_USERNAME/django-telescope.git
cd django-telescope
uv sync --dev
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
Make your changes in your feature branch
Follow code style:
# Check code style
uv run ruff check .
# Auto-fix style issues
uv run ruff check --fix .
# Format code
uv run ruff format .
Test your changes:
# Run the test suite
uv run python test_server.py
# Test with the fixture project
export PYTHONPATH="${PYTHONPATH}:./fixtures/testproject"
uv run django-telescope --settings testproject.settings
Commit your changes:
git add .
git commit -m "feat: add new feature" # or "fix: resolve bug"
We follow Conventional Commits:
feat: for new featuresfix: for bug fixesdocs: for documentation changeschore: for maintenance taskstest: for test changesrefactor: for code refactoringPush to your fork:
git push origin feature/your-feature-name
Create a Pull Request on GitHub from your fork to the main repository
ruff check) and formatting (ruff format)We're especially interested in:
Please be respectful and constructive in all interactions. We aim to maintain a welcoming and inclusive community.
FAQs
A Model Context Protocol (MCP) server for Django applications, inspired by Laravel Boost
The pypi package django-telescope receives a total of 34 weekly downloads. As such, django-telescope popularity was classified as not popular.
We found that django-telescope demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
The campaign amassed more than 75,000 installs by targeting Russian-speaking users seeking access to blocked services.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.