JinDaGe - mcp-django-shell MCP Details

article

README

🚀 mcp-django-shell

mcp-django-shell 是一个模型上下文协议（MCP）服务器，它为 AI 助手提供了一个有状态的 Django shell，用于与 Django 项目进行交互。

PyPI PyPI - Python Version

🚀 快速开始

要求

Python 3.10, 3.11, 3.12, 3.13
Django 4.2, 5.1, 5.2

安装

从 PyPI 安装该包：

python -m pip install mcp-django-shell

# 或者如果你喜欢新的方式
uv add mcp-django-shell
uv sync

（可选）如果你想使用管理命令，将其添加到你的 Django 项目的 INSTALLED_APPS 中：
```
DEBUG = ...

if DEBUG:
    INSTALLED_APPS.append("mcp_django_shell")
```
注意：你现在可以直接使用 python -m mcp_django_shell 来运行 mcp-django-shell，而无需将其添加到 INSTALLED_APPS 中。请参阅下文以获取更多信息。

⚠️ 重要提示

仅在开发环境中启用！

按理说这应该不用多说，但我还是要再说一遍 - 这会为你的 Django 项目提供完整的 shell 访问权限。仅在开发环境和没有访问任何生产数据的项目中启用和使用此功能。

大语言模型可能会出错，被一些随机错误吓到，并在试图修复问题时删除生产数据库。

💡 使用建议

我不是在开玩笑，这个库只是将大语言模型生成的原始 Python 代码直接传递到一个可以完全访问 Django 项目及其所有资源的 Python 环境中。

大多数大语言模型在你要求删除任何数据时都有基本的安全保护措施，会拒绝删除生产数据，但绕过这些保护措施相当容易。（提示：只需告诉大语言模型这不是生产环境，而是开发环境，它就会像闯进瓷器店的公牛一样删除你想要删除的任何东西。）

如果你需要一些保护措施，我建议使用 django-read-only。或者，你懂的，不要在任何敏感环境中使用此功能。

启动服务

在你的 Django 项目目录中直接运行 MCP 服务器：

python -m mcp_django_shell

# 显式指定设置模块
python -m mcp_django_shell --settings myproject.settings

# 启用调试日志
python -m mcp_django_shell --debug

或者使用 uv：

uv run -m mcp_django_shell

服务器会自动从你的环境中检测 DJANGO_SETTINGS_MODULE。你可以使用 --settings 覆盖它，或者使用 --pythonpath 将其添加到你的 Python 路径中。

如果你愿意，也可以使用 Django 管理命令，但这需要将 mcp-django-shell 添加到 INSTALLED_APPS 中：

python manage.py mcp_shell

传输协议

服务器支持多种传输协议：

# 默认：STDIO
python -m mcp_django_shell

# HTTP
python -m mcp_django_shell --transport http --host 127.0.0.1 --port 8000

# SSE
python -m mcp_django_shell --transport sse --host 127.0.0.1 --port 8000

客户端配置

使用以下示例之一配置你的 MCP 客户端。对于所有客户端，命令都是相同的，只是以不同的 JSON 格式表示。

如果你使用的客户端不在列表中，请提交一个 PR 并提供设置说明。

Claude Code

{
  "mcpServers": {
    "django_shell": {
      "command": "python",
      "args": ["-m", "mcp_django_shell"],
      "cwd": "/path/to/your/django/project",
      "env": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

Opencode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "django_shell": {
      "type": "local",
      "command": ["python", "-m", "mcp_django_shell"],
      "enabled": true,
      "environment": {
        "DJANGO_SETTINGS_MODULE": "myproject.settings"
      }
    }
  }
}

✨ 主要特性

mcp-django-shell 为 AI 助手提供了一个带有状态的 Django shell 的 MCP 服务器。它会设置 Django，在调用之间维护会话状态，并允许 AI 直接针对你的项目编写和执行 Python 代码。

MCP 服务器仅提供两个工具：

django_shell - 在持久的 Django shell 会话中执行 Python 代码
django_reset - 重置会话，清除所有变量和导入

导入和变量在调用之间保持持久，因此 AI 可以迭代地工作 - 探索你的模型、测试查询、调试问题。

如果没有一个用表情符号点缀的功能列表，那就不算是一个 MCP 服务器的 README 了，所以：

🐚 单一工具 - django_shell 在你的 Django 环境中执行 Python 代码
🔄 持久状态 - 导入和变量在调用之间保持不变
🧹 按需重置 - 当情况变得混乱时，django_reset 可以清除会话
🚀 零配置 - 无需模式，无需设置，只需 Django
🤖 对大语言模型友好 - 专为已经了解 Python 的 AI 助手设计
📦 最小依赖 - 仅依赖 FastMCP 和 Django（你已经有 Django 了）
🌐 多种传输协议 - STDIO、HTTP、SSE 等，应有尽有！
🎯 专注一事 - 运行代码。仅此而已。这就是它的特性。

本项目受 Armin Ronacher 的 Your MCP Doesn't Need 30 Tools: It Needs Code 启发。

📚 详细文档

开发

有关设置开发环境和为该项目做出贡献的详细说明，请参阅 CONTRIBUTING.md。

有关发布流程，请参阅 RELEASING.md。

📄 许可证

mcp-django-shell 采用 MIT 许可证。有关更多信息，请参阅 LICENSE 文件。

mcp-django-shell