Joomla MCP

Joomla MCP サーバー

既存の Joomla 4 または 5 のウェブサイトに AI アシスタントを接続すると、記事、カテゴリ、タグ、その他の対応するサイトコンテンツを読み取り、管理できるようになります。

2 か所を設定します。Joomla ウェブサイトと、AI アシスタントを実行するコンピューターです。この Python サーバーはコンピューター上で動作し、HTTPS 経由で Joomla 組み込みの Web Services API を呼び出します。このリポジトリを Joomla 拡張機能としてインストールしたり、ウェブホストにアップロードしたりする必要はありません。AI アプリは、stdio を使用するローカル MCP サーバーに対応している必要があります。以下の例では Claude Desktop を使用します。

Joomla ウェブサイトを設定する

1. 必要なプラグインを有効にする

Super User として Joomla Administrator にサインインします。システム → 管理 → プラグイン（管理者画面のレイアウトによっては システム → プラグイン）を開きます。以下を検索して有効にします。

プラグイン	用途
API Authentication - Web Services Joomla Token	トークンを使用した API リクエストの認証
User - Joomla API Token	ユーザーの API トークンの作成と管理
Web Services - Content	記事、コンテンツカテゴリ、記事フィールド

まずはこの 3 つから始めてください。追加のツールが必要な場合は、対応する Web Services - Tags、Media、Menus、Modules または Users プラグインも有効にしてください。メディアツールには Joomla 4.1 以降が必要です。カスタムフィールドには、Joomla の Fields コンポーネントとフィールドプラグインも必要です。

2. アシスタントが使用する Joomla アカウントを選ぶ

API トークンは Joomla ユーザーに紐付けられます。リクエストには、そのユーザーの権限が適用されます。普段使用する Super User アカウントではなく、この接続専用のアカウントを使用してください。

専用アカウントを作成する場合：

1. ユーザー → グループ → 新規を開き、MCP Content Editors のようなグループを作成します。最初は制限された権限にする場合、親グループとして 登録済みを選択します。
2. システム → グローバル設定 → 権限を開き、作成したグループを選択して、Web Services Login（core.login.api）を許可します。また、このアカウントが自分のプロフィールを開いてトークンをコピーできるように、Administrator Login も許可します。計算された権限が「許可」になっていることを確認し、Super User アクセスは設定しないでください。
3. 記事を管理するには、コンテンツ → 記事 → オプション → 権限を開きます。記事コンポーネントに対する 管理インターフェースへのアクセスをグループに付与し、そのうえで必要な操作のみを許可します。新しい記事には 作成、更新には 編集、公開、公開停止、ゴミ箱への移動には 状態の編集を許可します。カテゴリの権限で、これらの操作をさらに制限できます。ほかのコンポーネントのツールを使用する場合にのみ、そのコンポーネントの権限を設定してください。
4. ユーザー → 管理 → 新規を開き、専用アカウントを作成してグループに割り当てます。アカウントが有効化され、アクティベート済みで、ブロックされていないことを確認します。
5. システム → プラグインに戻り、User - Joomla API Tokenを開いて、このユーザーのグループを許可するユーザーグループに追加し、保存します。初期設定では Super User のみが許可されていることが多いため、新しく作成したアカウントにはトークンタブが表示されない場合があります。すべてのアカウントを対象にするためだけに、グループ制限を解除しないでください。

別のグループやカテゴリから継承した明示的な「拒否」権限は、子グループで許可しても変更できません。それでもアクセスが拒否される場合は、Joomla 管理者に計算された権限を確認してもらってください。API トークンを作成しても、追加の権限は付与されません。

3. アカウントの API トークンをコピーする

トークンを使用するアカウントとして Joomla にサインインします。Administrator の右上にあるユーザーメニューから自分のプロフィールを開き （バージョンによって Edit Account または Profile）、Joomla API Token を選択します。

• Joomla に「このアカウントにはまだトークンがありません」と表示された場合は、プロフィールを保存してから再度開きます。
• Active が表示されている場合は Yes に設定して、保存します。
• Token の値をコピーします。これを下の BEARER_TOKEN に設定します。
• Reset → Yes を選択して保存すると、トークンが置き換えられ、古いトークンは無効になります。

自分のトークンのみ表示できます。Super User として別のユーザーのアカウントを編集しても、そのユーザーのトークンはコピーできません。タブが表示されない場合は、トークンプラグインと許可されているグループを確認してください。 Joomla のトークンプラグインの設定とプロフィールのコントロールを参照してください。

コンピューターでサーバーをセットアップする

4. Git と uv をインストールして、このリポジトリをダウンロードする

MCP 対応の AI アプリを実行するコンピューターを使用します。git --version が動作しない場合は、 Git をインストールしてください。

Python とこのサーバーの依存関係を管理する uv をインストールします。macOS/Linux の場合：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows では、PowerShell を使用します：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

インストール後にターミナルを再度開き、どちらのプラットフォームでも次のコマンドを実行します：

uv --version
git clone https://github.com/nasoma/joomla-mcp-server.git
cd joomla-mcp-server
uv python install 3.14.8
uv sync --locked

すでにこのリポジトリをクローンしている場合は、再度クローンせず、そのフォルダーを開いてください。 uv sync によりローカルの .venv が作成され、サーバーがインストールされます。環境を有効化する必要はありません。

5. ウェブサイトの URL とトークンをローカルの .env ファイルに設定する

リポジトリのフォルダーで、.env.example を .env にコピーします。

macOS/Linux：

cp .env.example .env

Windows PowerShell：

Copy-Item .env.example .env

テキストエディターで .env を開き、次の値を置き換えます：

JOOMLA_BASE_URL=https://your-joomla-site.com
BEARER_TOKEN=paste-your-own-joomla-api-token-here
JOOMLA_VERSION=5
JOOMLA_READ_ONLY=true

サイトで Joomla 4 を使用している場合は、JOOMLA_VERSION=4 を設定します。初回の接続では、ほかのサンプル設定は変更しないでください。JOOMLA_READ_ONLY=true を設定すると、アシスタントによるウェブサイトの変更を許可せずに、まずアクセスを確認できます。

サイトの公開 HTTPS URL を使用します。Joomla がサブフォルダーにある場合は、https://example.com/joomla のように含めてください。末尾に /administrator や /api/index.php/v1 を追加しないでください。API パスはサーバーが自動的に追加します。ホストまたはファイアウォールで、その API へのアクセスが許可されている必要があります。

.env は非公開にしてください。Git では無視されます。このファイルを共有したり、この README のプレースホルダーを実際のトークンに置き換えたりしないでください。macOS/Linux では、chmod 600 .env でアクセスを制限できます。 サーバーは環境変数を読み込みます。uv がこのファイルを読み込むのは、--env-file を指定した場合のみです。

6. サーバーが起動することを確認する

リポジトリのフォルダーから、次を実行します：

uv run --locked --env-file .env joomla-mcp

起動したサーバーは通常、MCP クライアントからの接続を待機し、何も表示しません。ブラウザーを開いたり、記事一覧を出力したり、ウェブページを起動したりすることはありません。この手動起動を停止するには、Ctrl+C を押します。 正常に起動すればローカルの設定を確認できます。Joomla ウェブサイトへのアクセス確認は、手順 7 の最初のツールリクエストで行います。

AI アシスタントを接続する

7. サーバーを Claude Desktop に追加する

お使いのコンピューターに Claude Desktop をインストールして開きます。これらの設定はローカルの 設定ファイルに記述します。チャットメッセージや Claude のウェブサイトのコネクター URL 欄には入力しません。 Claude Desktop がサーバーを起動するため、手順 6 を実行したままにする必要はありません。

まず、クローンした joomla-mcp-server フォルダー内でターミナルを開き、次の 2 つのパスを確認します。

JSON 内のプレースホルダー	macOS/Linux のコマンド	Windows PowerShell のコマンド
{{PATH_TO_UV}}	which uv	(Get-Command uv).Source
{{PATH_TO_PROJECT}}	pwd	(Get-Location).Path

各コマンドの出力をコピーします。たとえば、which uv は /Users/you/.local/bin/uv、pwd は /Users/you/joomla-mcp-server を返す場合があります。 完全なパスを含め、ご自身の出力を使用してください。~ は使わず、プレースホルダーをそのまま残さないでください。

設定ファイルを開きます。

1. macOS では、メニューバーから Claude → Settings… を選択します。Windows では、 Claude Desktop アプリの Settings を開きます。
2. Developer → Edit Config を選択します。claude_desktop_config.json が開きます。
3. ファイルが空の場合は、以下の JSON 全体を貼り付けます。すでに mcpServers が含まれている場合は、 そのオブジェクト内に Joomla Articles MCP のエントリを追加し、既存のサーバーはそのまま残します。

手動で開く場合、ファイルは次の場所にあります。

システム	設定ファイル
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

macOS では、Finder の Go → Go to Folder… を使って ~/Library/Application Support/Claude を開きます。 Windows では、Win+R を押し、%APPDATA%\Claude を入力して、そこでファイルを開きます。 公式の Claude Desktop のローカル MCP ガイドを参照してください。

{
  "mcpServers": {
    "Joomla Articles MCP": {
      "command": "{{PATH_TO_UV}}",
      "args": [
        "--directory",
        "{{PATH_TO_PROJECT}}",
        "run",
        "--locked",
        "--env-file",
        "{{PATH_TO_PROJECT}}/.env",
        "joomla-mcp"
      ]
    }
  }
}

{{PATH_TO_UV}} を uv のパスに置き換え、{{PATH_TO_PROJECT}} の両方をリポジトリのパスに置き換えます。2 回目の箇所にある /.env はそのまま残してください。これは手順 5 で作成したファイルを指しています。JSON にコメントを含めないでください。

Windows では、uv.exe の完全なパスを使用します。C:/Users/you/joomla-mcp-server のようにスラッシュを使うか、 C:\\Users\\you\\joomla-mcp-server のように JSON 内で各バックスラッシュを 2 つ重ねてください。この JSON にトークンをコピーする必要はありません。 uv はローカルの .env ファイルからトークンを読み込みます。

ファイルを保存し、Claude Desktop を完全に終了してから再度開きます。会話画面で Add files, connectors, and more → Connectors → Manage connectors を開き、 Joomla Articles MCP が利用可能であることを確認します。次に、以下のように依頼します。

get_joomla_articles を使って、Joomla ウェブサイトにある最初の 5 件の記事を一覧表示してください。何も変更しないでください。

Claude から求められた場合は、読み取りリクエストを承認します。成功すると、記事 ID とタイトルが返されます。 アカウントから記事を参照できない場合は、空のリストが返されます。空のリストは API エラーとは異なります。

別の MCP アプリを使う場合は、同じコマンドと引数を、そのアプリのローカル／stdio サーバー 設定に記述します。このサーバーは、リモートコネクター用の HTTP MCP URL を提供しません。

8. 準備ができたらコンテンツの変更を有効にする

読み取りリクエストが成功したら、.env の次の行を変更します。

JOOMLA_READ_ONLY=false

設定を再読み込みするため、AI アプリを再起動します。実行できる変更は、引き続きアカウントの Joomla 権限によって制御されます。 新しい記事は、デフォルトで未公開の下書きになります。更新には既存のタイトルとの完全一致が必要です。 ゴミ箱への移動にも明示的な確認が必要です。たとえば、次のように依頼します。

コンテンツのカテゴリーを表示してから、私が選ぶカテゴリーに「MCP setup check」という未公開の下書きを作成してください。

オプション機能は後から有効にできます。フィルター付きのユーザー読み取りには JOOMLA_ENABLE_USERS=true を使用し、 他のツール群には対応する Joomla Web Services プラグインを有効にしてください。

記事カテゴリの選択

create_article と update_article では、category_id または category_name を指定できます。 たとえば、「記事 87 を Blog に移動して」と指示する場合は、category_name="Blog" を使用できます。サーバーはカテゴリ名と完全一致する大文字小文字を区別しない一致を検索し、カテゴリ ID を特定します。利用可能なすべてのカテゴリページ（最大 1,000 カテゴリ）を確認するため、最初のページで見つかった一致によって、後のページにある重複が見落とされることはありません。

記事の作成時にカテゴリが指定されていない場合、名前が完全一致しない場合、または同じ名前のカテゴリが複数ある場合、サーバーは変更を行わず、使用するカテゴリ ID を確認するようアシスタントに伝えます。複数の候補がある場合は、候補の ID と親 ID が表示されます。名前と ID の両方を指定する場合は、両者が一致している必要があります。これらの確認メッセージはアシスタントとのチャットに表示され、サーバーがクライアント固有のポップアップを開くことはありません。

既存の記事を公開すると、現在のカテゴリが維持されます。別のカテゴリで公開するには、まず記事を移動するようアシスタントに依頼し、移動が成功した後に公開してください。

セットアップのトラブルシューティング

表示される内容	確認すること
Joomla API Token タブがない、またはトークンが空白	User - Joomla API Token を有効にし、アカウントのグループを Allowed User Groups に含め、そのアカウントでサインインしてから、プロフィールを保存して再度開いてください。
HTTP 401	API Authentication - Web Services Joomla Token、コピーしたトークン、およびその Active 設定を確認してください。トークンをリセットした場合は、.env を更新してクライアントを再起動してください。
HTTP 403	アカウントの Web Services Login 権限、グループの適格性、および要求された操作に対するコンポーネント／カテゴリの権限を確認してください。
HTTP 500	ツールは、利用可能な場合、Joomla の JSON エラーのタイトル／詳細を含めます。認証情報とパスは伏せられます。書き込みに失敗した場合、すでに保存されている可能性があるため、再試行する前に記事を確認してください。Joomla が内部サーバーエラーしか報告しない場合は、該当する PHP エラーログの記録をホスティング業者に問い合わせてください。ローカルの MCP stderr には HTTP ステータスのみが表示されます。
HTTP 404	サイトのルート／サブフォルダー URL と、対応する Web Services プラグインを確認してください。ホストは /api/index.php/v1/... をブロックせず、Joomla にルーティングする必要があります。
ネットワークエラーまたはタイムアウト	コンピューターからサイトの HTTPS URL にアクセスできること、およびホスト／ファイアウォールが API リクエストを許可していることを確認してください。
Joomla の応答が無効／JSON が必要	API の JSON ではなく、ログインページ、ホスティングエラー、またはファイアウォールのチャレンジが返された可能性があります。ホストに API ルートを確認してください。
URL／トークンに関する設定エラー	.env に両方の値が含まれていること、およびクライアントコマンドに正しい絶対パスの --env-file が指定されていることを確認してください。
AI アプリにサーバーが表示されない	JSON の構文、絶対パス、uv --version を確認してください。アプリを完全に再起動し、MCP のエラーログを調べてください。
ターミナルでサーバーが無反応のまま待機する	stdio では想定どおりの動作です。手順 7 の説明に従って AI アプリを接続してください。
書き込みが無効になっている	.env の JOOMLA_READ_ONLY を false に変更し、アプリを再起動してください。

Joomla のWeb Services ガイド では、API とアカウントの前提条件について説明しています。セットアップのサポートを求める際に、トークンを投稿しないでください。

ツール

領域	ツール
記事	get_joomla_articles、get_joomla_article、create_article、update_article、manage_article_state、move_article_to_trash
カテゴリー	get_joomla_categories、get_joomla_category、create_category、update_category、delete_category
タグ	get_joomla_tags、get_joomla_tag、create_tag、update_tag、delete_tag。記事へのタグ割り当ては update_article(tags=[IDs]) で行います
フィールド	get_joomla_fields、get_joomla_field、create_field、update_field、delete_field、get_joomla_field_groups、get_joomla_field_group、create_field_group、update_field_group、delete_field_group、get_article_fields、update_article_fields
メディア	get_joomla_media、get_joomla_media_file、upload_media、update_article_images
サイトメニュー	get_joomla_menus、get_joomla_menu、create_menu、update_menu、delete_menu、get_joomla_menu_items、get_joomla_menu_item、create_menu_item、update_menu_item、delete_menu_item
サイトモジュール	get_joomla_modules、get_joomla_module、create_custom_module、update_module、delete_module
ユーザー（オプトイン）	get_joomla_users、get_joomla_user。読み取り専用

ツールの入力スキーマには、型、範囲、説明が含まれます。ID は正の整数である必要があり、 ブール値や数値文字列は受け付けません。リストはデフォルトで 20 行を返し、最大 100 行まで指定できます。 記事の場合は、search/category_id/state/tag_id フィルターを使用し、pagination.next_offset に従ってください。 記事一覧では、デフォルトで本文が省略されます。本文を取得するには include_content=true を指定するか、詳細を参照してください。 Joomla はメディアディレクトリのページネーションに対応していないため、ディレクトリのサイズはバイト数で制限され、ローカルで分割されます。

成功時の結果は、ok: true、正規化された data、および任意の pagination、updated_fields、changed を含む構造化オブジェクトです。 結果内のリソース ID は文字列です。ツールを呼び出す際は、ID を整数として指定してください。エラーは MCP ツールエラー（is_error=true）として、安全な長さに制限されたメッセージとともに返されます。API の本文、認証情報、生のネットワーク例外は返されません。

設定

変数	デフォルト	意味
JOOMLA_BASE_URL、BEARER_TOKEN	必須	HTTPS サイトのルート URL とシークレットトークン
JOOMLA_VERSION	5	サポートされるメジャーバージョン。4 または 5。ツールは共通の API コントラクトを使用します
JOOMLA_READ_ONLY	false	変更操作を拒否します
JOOMLA_ALLOW_TRUSTED_HTML	false	明示的に選択した信頼できる HTML を許可します
JOOMLA_ENABLE_USERS	false	フィルター付きのユーザー読み取りツールを登録します
JOOMLA_ALLOW_LOCAL_HTTP	false	ループバック開発用の例外を許可します
JOOMLA_TIMEOUT	20	リクエストごとのタイムアウト（秒、最大 120）
JOOMLA_READ_RETRIES	2	安全な読み取りの追加試行回数（0～3）。書き込みは再試行されません
JOOMLA_MAX_RESPONSE_BYTES	2000000	デコード後の API レスポンスの最大バイト数
JOOMLA_MAX_UPLOAD_BYTES	5000000	デコード後の画像アップロードの最大バイト数

ブール値には true/false または 1/0 を指定できます。リダイレクトとプロキシ環境変数の参照は無効です。 Retry-After の値が 5 秒を超える読み取りでは、失敗を返し、呼び出し元が再スケジュールできるようにします。

ライセンス

MIT。詳しくは LICENSE を参照してください。