# django-mcp-inspector

Starts a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes
Django runtime information as resources, allowing AI agents to inspect a live Django
project without any static file analysis.

## Resources

| URI | Contents |
|-----|----------|
| `django://settings` | All settings (sensitive values redacted) |
| `django://apps` | Installed apps, labels, paths, model names |
| `django://urls` | URL pattern tree flattened to pattern / view / name |
| `django://models` | Every model's fields, types, and relations |
| `django://models/{app_label}` | Fields for a single app |
| `django://migrations` | Applied and pending migrations per app |

## Usage

### Zero project modification (recommended)

Run as an ephemeral tool — no changes to `INSTALLED_APPS` or requirements:

```shell
DJANGO_SETTINGS_MODULE=myproject.settings uv run --with django-mcp-inspector django-mcp-inspector
```

Pass `--settings` instead of the environment variable if you prefer:

```shell
uv run --with django-mcp-inspector django-mcp-inspector --settings myproject.settings
```

Exclude third-party app noise:

```shell
uv run --with django-mcp-inspector django-mcp-inspector --settings myproject.settings --exclude-site-packages
```

### As an installed app

Add `mcp_inspector` to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...
    'mcp_inspector',
]
```

Then run the management command:

```shell
python manage.py mcpserver
python manage.py mcpserver --exclude-site-packages
```

## Connecting an MCP client

The server communicates over **stdio**.  Point any MCP-compatible client
(Claude Desktop, custom agent, etc.) at the process.

Example Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "django": {
      "command": "uv",
      "args": [
        "run", "--with", "django-mcp-inspector",
        "django-mcp-inspector", "--settings", "myproject.settings"
      ],
      "env": {
        "PYTHONPATH": "/path/to/your/project"
      }
    }
  }
}
```

## Requirements

- Python 3.12+
- Django 4.2+
- mcp 1.0+