Django MCP Server

Django MCP Server

Django MCP Server は、Django 向けの Model Context Protocol（MCP） 拡張の実装です。このモジュールを使用すると、MCP クライアントやAI エージェントが、あらゆる Django アプリケーションとシームレスにやり取りできます。

🚀 Django らしい宣言型のツールにより、AI エージェントや MCP クライアントが Django とやり取りできます。
🚀 Django モデルを AI エージェントや MCP ツールに公開し、安全に 2 行のコードでクエリできます。
🚀 Django Rest Framework の API を、1 つのアノテーションで MCP ツールに変換できます。
✅ インフラストラクチャを変更せずに、WSGI と ASGI の両方で動作します。
✅ Claude AI とのリモート連携として検証済みです。
🤖 MCP をサポートするあらゆる MCP クライアントまたは AI エージェント（Google Agent Developement Kit、Claude AI、Claude Desktop など）が、アプリケーションとやり取りできます。

貢献者コミュニティの皆さんに心より感謝します 🙏

Smart GTS software engineering が ✨ 丁寧にメンテナンスしています。

MIT License の下でライセンスされています。

---

機能

• Django モデルとロジックを MCP ツールとして公開します。
• Django アプリ内で MCP エンドポイントを提供します。
• AI エージェント、MCP クライアント、または Google ADK などのツールと簡単に連携できます。

---

クイックスタート

1️⃣ インストール

pip install django-mcp-server

または GitHub から直接インストールします。

pip install git+https://github.com/omarbenhamid/django-mcp-server.git

---

2️⃣ Django の設定

✅ mcp_server を INSTALLED_APPS に追加します。

INSTALLED_APPS = [
    # your apps...
    'mcp_server',
]

✅ MCP エンドポイントを urls.py に追加します。

from django.urls import path, include

urlpatterns = [
    # your urls...
    path("", include('mcp_server.urls')),
]

デフォルトでは、MCP エンドポイントは /mcp で利用できます。

---

3️⃣ MCP ツールの定義

mcp.py で ModelQueryToolset のサブクラスを作成し、モデルへのアクセスを許可します。

from mcp_server import ModelQueryToolset
from .models import *


class BirdQueryTool(ModelQueryToolset):
    model = Bird

    def get_queryset(self):
        """self.request can be used to filter the queryset"""
        return super().get_queryset().filter(location__isnull=False)

class LocationTool(ModelQueryToolset):
    model = Location

class CityTool(ModelQueryToolset):
    model = City

または、汎用メソッドを公開するために MCPToolset のサブクラスを作成します（非公開の _ メソッドは公開されません）。

例：

from mcp_server import MCPToolset
from django.core.mail import send_mail

class MyAITools(MCPToolset):
    def add(self, a: int, b: int) -> list[dict]:
        """A service to add two numbers together"""
        return a+b

    def send_email(self, to_email: str, subject: str, body: str):
        """ A tool to send emails"""

        send_mail(
             subject=subject,
             message=body,
             from_email='[email protected]',
             recipient_list=[to_email],
             fail_silently=False,
         )

---

MCP Inspect で検証する

管理コマンド mcp_inspect を使用して、ツールが正しく宣言されていることを確認します。

python manage.py mcp_inspect

任意の MCP クライアントで MCP を使用する

MCP ツールは、/mcp エンドポイントで Django アプリに公開されています。

IMPORTANT 本番環境で非公開データを扱う場合は、以下を通じて認証を有効にすることを検討してください：DJANGO_MCP_AUTHENTICATION_CLASSES

MCP Python SDK でテストする

Python の mcp SDK でテストできます。

from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession


async def main():
    # Connect to a streamable HTTP server
    async with streamablehttp_client("http://localhost:8000/mcp") as (
        read_stream,
        write_stream,
        _,
    ):
        # Create a session using the client streams
        async with ClientSession(read_stream, write_stream) as session:
            # Initialize the connection
            await session.initialize()
            # Call a tool
            tool_result = await session.call_tool("get_alerts", {"state": "NY"})
            print(tool_result)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

http://localhost:8000/mcp を実際の Django ホストに置き換えて、このスクリプトを実行してください。

Claude AI から使用する

2025 年 6 月時点で、Claude AI はストリーミング可能な HTTP プロトコルを通じて MCP をサポートしています。前提条件は次のとおりです。 *

• OAuth2 を設定します。例：
  • Django Oauth Toolkit) をインストールします
  • settings.py の DJANGO_MCP_AUTHENTICATION_CLASSES に 'oauth2_provider.contrib.rest_framework.OAuth2Authentication' を含めます
• Claude AI では Dynamic Client Registration が必要です。現時点ではdjango oauth toolkit ではサポートされていませんが、この Django Oauth Toolkit DCR Add-On を使用できます
• OAuth server Metadata RFC を正しく実装しない限り、OAuth2 の URL（/register、/token、/authorize）をデフォルトの場所に維持する必要があります。

Claude Desktop でテストする

Claude Desktop で MCP サーバーをテストできます。現時点では、 Claude Desktop はローカルの MCP サーバーのみをサポートしています。そのため、開発環境でテストする場合は、 おそらくアプリを同じマシンにインストールする必要があります。

そのためには、次の手順が必要です。

1. claude.ai から Claude Desktop をインストールします
2. File > Settings > Developer を開き、Edit Config をクリックします
3. claude_desktop_config.json を開き、MCP サーバーを設定します。

   {
    "mcpServers": {
        "test_django_mcp": {
            "command": "/path/to/interpreter/python",
            "args": [
                "/path/to/your/project/manage.py",
                "stdio_server"
            ]
        }
    }
   

注記 /path/to/interpreter/ は使用する Python インタープリター（たとえば、venv 内のもの）を指し、 /path/to/your/project/ は Django プロジェクトのパスを指す必要があります。

高度なトピック

Django Rest Framework API を MCP ツールとして公開する

drf_publish_create_mcp_tool / drf_publish_update_mcp_tool / drf_publish_delete_mcp_tool / drf_publish_list_mcp_tool をアノテーションまたはメソッド呼び出しとして使用すると、DRF の CreateModelMixin / UpdateModelMixin / DestroyModelMixin / ListModelMixin ベースのビューを MCP ツールとしてシームレスに登録できます。Django MCP Server は、MCP クライアントがそれらを使用できるようにスキーマを生成します。

注記 一部の 古い DRF バージョン では、スキーマ生成が標準でサポートされていません。その場合は、登録用 アノテーションに以下を指定する必要があります。

from mcp_server import drf_publish_create_mcp_tool

@drf_publish_create_mcp_tool
class MyModelView(CreateAPIView):
    """
    A view to create MyModel instances
    """
    serializer_class=MySerializer

ビューの docstring がモデルへの指示として使用されることに注意してください。 次のように、さらに調整できます。

@drf_publish_create_mcp_tool(instructions="Use this view to create instances of MyModel")
class MyModelView(CreateAPIView):
    """
    A view to create MyModel instances
    """
    serializer_class=MySerializer

最後に、たとえば mcp.py で手動登録できます。

drf_publish_update_mcp_tool(MyDRFAPIView, instructions="Use this tool to update my model, but use it with care")

重要

組み込みの認証クラスはデフォルトで無効になっており、filter_backends、permission_classes、pagination_class も同様です。これは、 MCP の認証が使用されるためです。

pagination_class も無効になっているため、既存のページネーション対応 DRF ビューを使用する場合は、それを考慮する必要があります（self.paginator は None になります）。

Django Rest Framework Serializer の統合

ツールに drf_serialize_output(...) をアノテーションとして付けると、次のように Django Rest Framework を使用して出力をシリアライズできます。

from mcp_server import drf_serialize_output
from .serializers import FooBarSerializer
from .models import FooBar

class MyTools(MCPToolset):
   @drf_serialize_output(FooBarSerializer)
   def get_foo_bar():
       return FooBar.objects.first()

低レベルの MCP サーバーアノテーションを使用する

DjangoMCP サーバーインスタンスをインポートし、FastMCP アノテーションを使用して MCP ツールとリソースを宣言できます。

from mcp_server import mcp_server as mcp
from .models import Bird


@mcp.tool()
async def get_species_count(name: str) -> int:
    '''Find the ID of a bird species by name (partial match). Returns the count.'''
    ret = await Bird.objects.filter(species__icontains=name).afirst()
    if ret is None:
        ret = await Bird.objects.acreate(species=name)
    return ret.count

@mcp.tool()
async def increment_species(name: str, amount: int = 1) -> int:
    '''
    Increment the count of a bird species by a specified amount.
    Returns the new count.
    '''
    ret = await Bird.objects.filter(species__icontains=name).afirst()
    if ret is None:
        ret = await Bird.objects.acreate(species=name)
    ret.count += amount
    await ret.asave()
    return ret.count

⚠️ 重要：

1. 非同期ツールを定義する場合は、常に Django の非同期 ORM API を使用してください。
2. QuerySet を返さないように注意してください。非同期で評価されるため、エラーが発生します。

MCP サーバーのデフォルト設定をカスタマイズする

settings.py では、DJANGO_MCP_GLOBAL_SERVER_CONFIG パラメーターを初期化できます。これらは初期化時に MCPServer サーバーへ渡されます。

DJANGO_MCP_GLOBAL_SERVER_CONFIG = {
    "name":"mymcp",
    "instructions": "Some instructions to use this server",
    "stateless": False
}

セッション管理

デフォルトでは、サーバーはステートフルであり、状態は Django セッション の request.session オブジェクトとして管理されるため、セッションバックエンドを正しく設定する必要があります。 クラスベースのツールセットでは、リクエストオブジェクトを self.request から利用できます。

注記 MCP セッションは独立して管理され、Cookie を使用しないため、セッションミドルウェアを設定する必要はありません。 。 DJANGO_MCP_GLOBAL_SERVER_CONFIG を定義すると、サーバーをステートレスにできます。

重要 状態は Django セッションによって管理されます。たとえば、低レベルの @mcp_server.tool() アノテーションを使用する場合、 WSGI デプロイメントでは、リクエストが異なるスレッドによって処理される可能性があるという Django のアーキテクチャ上の理由から、 基本的な Python API の呼び出し間でサーバーインスタンスを保持する動作は維持されません。

認可

MCP エンドポイントは、Django Rest Framework の認証クラスをサポートしています。 settings.py の DJANGO_MCP_AUTHENTICATION_CLASSES を使用して設定できます。例：

DJANGO_MCP_AUTHENTICATION_CLASSES=["rest_framework.authentication.TokenAuthentication"]

重要 現在の MCP Specification バージョン 2025-03-26では、OAuth2 ワークフローの使用が推奨されています。そのため、 django-oauth-toolkit と djangorestframework の連携 をセットアップし、DJANGO_MCP_AUTHENTICATION_CLASSES に 'oauth2_provider.contrib.rest_framework.OAuth2Authentication' を指定してください。django-oauth-toolkit の公式ドキュメントを参照してください。

ビューの高度なカスタマイズ設定

urls.py で MCPServerStreamableHttpView.as_view() ビューをマウントし、任意の追加パラメーターを使ってカスタマイズできます。

ModelQueryToolset のカスタム出力形式（レンダラー）

出力を生成するために、任意の DRF レンダラーを定義できます。そのためには、 設定で宣言する必要があります。

DJANGO_MCP_OUTPUT_RENDERER_CLASSES = [
    "rest_framework.renderers.JSONRenderer",
    "rest_framework_csv.renderers.CSVRenderer"
]

次に、ModelQueryToolset の宣言に以下を追加できます。

    ...
    output_format="csv"

さらに、結果を直接返すのではなく、[MCP Embedded Resource] として添付するようツールに指示するには、以下を使用します。

    ...
    output_as_resource=True

注意 drf-excel など、一部のレンダラーは DRF ビュー以外での使用を許可しない設計になっているため、ここでは動作しません。

2 つ目の MCP エンドポイント

mcp.py 内

from mcp_server.djangomcp import DjangoMCP

second_mcp = DjangoMCP(name="altserver")

@second_mcp.tool()
async def my_tool():
    ...

urls.py 内

...
from yourapp.mcp import second_mcp
...
path("altmcp", MCPServerStreamableHttpView.as_view(mcp_server=second_mcp))
...

重要 このようにすると、DJANGO_MCP_AUTHENTICATION_CLASSES の設定は無視され、ビューは保護されません。ビューに対してDRF 認証をセットアップする必要があります。例：

...
MCPServerStreamableHttpView.as_view(permission_classes=[IsAuthenticated], authentication_classes=[TokenAuthentication])
...

テスト

サーバー

独自のアプリをセットアップするか、mcpexample django app アプリを使用できます。

クライアント

デフォルトでは、MCP サーバーは ステートレスなストリーマブル HTTP トランスポート のエンドポイントとして <your_django_server>/mcp で利用できます（例：http://localhost:8000/mcp）（末尾に / は付けません！）。

テストにはさまざまな方法があります。

1. テスト用の MCP クライアントスクリプト：test/test_mcp_client.py を使用します。
2. MCP Inspector ツールを使ってテストできます。
3. または、Google Agent Development Kit など、互換性のある MCP クライアントを使用します。

---

エージェントフレームワークおよび MCP クライアントとの連携

Google Agent Development Kit の例

注意 現時点では、Google ADK の公式版は StreamableHTTP Transport をサポートしていませんが、このフォークを使用できます。

次に、test フォルダーで adk web を起動して、test/test_agent 内のテストエージェントを使用できます。最初に以下を確認してください。

1. StreamableHTTP をサポートする ADK をインストールします：pip install git+https://github.com/omarbenhamid/google-adk-python.git
2. examples/mcpexample フォルダーで python manage.py runserver を実行し、MCP エンドポイントを含む Django アプリを起動します。
3. TokenAuthorization を使用する場合は、アプリの Django Admin などでアクセストークンを作成します。
4. test/test_agent/agent.py で、正しいエンドポイントの場所と認証ヘッダーを設定します。
5. test フォルダーに移動します。
6. adk web を実行します。
7. シェルで、たとえば次のプロンプトを使用できます："I saw woody woodpecker, add it to my inventory"

その他のクライアント

MCP ストリーマブル HTTP サーバーをサポートするエージェントフレームワークであれば、MCP サーバーのエンドポイントを簡単に接続できます。 クライアントの一覧を参照してください。

---

設定

• DJANGO_MCP_GLOBAL_SERVER_CONFIG グローバル MCP サーバーの設定辞書です。デフォルトは空です。以下のパラメーターを含めることができます。

  • name: サーバー名
  • instructions: グローバルな指示
  • stateless : 'True' に設定すると、サーバーはセッションを管理しません

• DJANGO_MCP_AUTHENTICATION_CLASSES（デフォルトでは認証なし）メインの MCP ビューで適用する Django Rest Framework 認証クラスへの参照のリストです。

• DJANGO_MCP_GET_SERVER_INSTRUCTIONS_TOOL（デフォルト=True）true の場合、グローバルな指示を取得するツールが提供され、エージェントにはそのツールを使用するよう指示されます。エージェントのシステムプロンプトに MCP サーバーのグローバルな指示が常に含まれているとは限らないためです。

• DJANGO_MCP_ENDPOINT（デフォルト="mcp"）サーバーが使用する URL エンドポイントを示す文字列です。末尾にスラッシュを付ける場合は、たとえば "mcp/" に設定します。

ロードマップ

• ✅ ステートレスなストリーミング可能 HTTP トランスポート（実装済み）
• 🔜 開発設定用の STDIO トランスポート統合（例：Claude Desktop）
• 🔜 ****
• 🔜 Django セッションを使用したステートフルなストリーミング可能 HTTP トランスポート
• 🔜 SSE エンドポイント統合（ASGI が必要）
• 🔜 エラー管理とロギングの改善

---

課題

バグを見つけた場合や機能のリクエストがある場合は、GitHub Issues でイシューを作成してください。

---

ライセンス

MIT License。