ATTENTION: LLM-GENERATED CODE

LimeSurvey MCP サーバー

LimeSurvey Remote API の機能を MCP ツールとして公開する Model Context Protocol（MCP）サーバーです。このサーバーにより、MCP クライアントを通じて LimeSurvey の強力なアンケート管理機能を標準化された方法で利用できます。

目次

• インストール
• 設定
• 使い方
• API リファレンス
  • アンケート管理
  • 質問管理
  • 回答管理
  • 参加者管理
  • 統計管理
• 開発
• ライセンス

インストール

# Clone the repository
git clone https://github.com/TonisOrmisson/limesurvey-mcp.git
cd limesurvey-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

設定

ルートディレクトリに、次の変数を含む .env ファイルを作成してください。

# LimeSurvey Remote API Settings
LIMESURVEY_API_URL=https://your-limesurvey-instance.com/admin/remotecontrol
LIMESURVEY_USERNAME=your_username
LIMESURVEY_PASSWORD=your_password

# Server settings
PORT=3000
ENABLE_SSE=false

# Optional: run in read‑only mode
# When true, all write tools short‑circuit and return an error message
# instead of calling LimeSurvey.
READONLY_MODE=false

使い方

サーバーが起動したら、任意の MCP クライアントを接続して LimeSurvey の機能を利用できます。

デフォルトでは、サーバーは stdio のみで起動します。MCP サーバーがクライアントによってローカルで起動されるのではなく、リモートで実行される場合など、/sse と /messages で HTTP/SSE トランスポートを使用するには、ENABLE_SSE=true を設定してください。

ヘッドレスでのアンケート作成（addSurvey → グループ → 質問）

LimeSurvey の管理 UI を使わずに、書き込みツールを組み合わせてアンケートを作成できます。

1. addSurvey — 非アクティブなアンケートを作成します。返されたアンケート ID（sid）を控えてください。
2. addGroup — 1 つ以上の質問グループを作成します。各呼び出しで、次の手順に使用するグループ ID（gid）が返されます。
3. importQuestion — 質問ごとに、base64 でエンコードされた .lsq コンテンツを渡します（UI からプロトタイプの質問を一度エクスポートするか、互換性のある XML を生成してください）。importDataType: lsq を使用します。
4. setSurveyProperties — ウェルカムテキスト、説明、終了 URL などを設定します。
5. activateSurvey — 構成が整ったら、アンケートを有効化します。

冪等な再構築： グループまたは個別の質問を削除してから .lsq テンプレートを再インポートするには、deleteQuestion（qid ごとに、confirmDeletion: true を指定）と deleteGroup（アンケートと gid を指定）を使用します。グループを削除すると、そのグループのコンテンツも削除されます。まず開発用アンケートで、ご利用の LimeSurvey バージョンの確認動作を確かめてください。

参加者リンクの形式： https://<host>/index.php/<sid>（addSurvey または listSurveys の sid を使用）。トークンを使用したアクセスには、既存の参加者ツールを使用してください。

アンケート一覧を取得する MCP クライアントのスニペットの例（擬似 YAML）：

tool: listSurveys
args: {}

API リファレンス

RemoteControl2 の対応状況

以下の表は、LimeSurvey RemoteControl2 のメソッドが、このサーバーでどのように MCP ツールとして公開されているかを示しています。実装されていないメソッドは、対象の LimeSurvey インスタンスで利用できないか、不安定または文書化されていないエンドポイントなどの理由で意図的に除外されています。

ドメイン	RemoteControl2 メソッド	MCP ツール名	備考
アンケート	list_surveys	listSurveys	読み取り専用
アンケート	get_survey_properties	getSurveyProperties	読み取り専用
アンケート	activate_survey	activateSurvey	書き込み（READONLY_MODE で制限）
アンケート	get_language_properties	getSurveyLanguageProperties	読み取り専用
アンケート	get_site_settings	getAvailableLanguages	availablelanguages 設定を読み取ります
アンケート	—（派生）	getSurveyLanguages	アンケートのプロパティから派生
アンケート	get_fieldmap	getFieldMap	読み取り専用
アンケートのライフサイクル	add_survey	addSurvey	書き込み（制限あり）
アンケートのライフサイクル	import_survey	importSurvey	書き込み（制限あり）
アンケートのライフサイクル	copy_survey	copySurvey	書き込み（制限あり）
アンケートのライフサイクル	delete_survey	deleteSurvey	書き込み（制限あり、確認が必要）
アンケートのライフサイクル	activate_tokens	activateTokens	書き込み（制限あり）
アンケートのライフサイクル	set_survey_properties	setSurveyProperties	書き込み（制限あり）
質問グループ	list_groups	listQuestionGroups	読み取り専用
質問グループ	get_group_properties	getGroupProperties	読み取り専用
質問グループ	add_group	addGroup	書き込み（制限あり）；新しい gid を返します
質問グループ	delete_group	deleteGroup	書き込み（制限あり、確認が必要）
質問グループ	set_group_properties	setGroupProperties	書き込み（制限あり）
質問	list_questions	listQuestions	読み取り専用
質問	get_question_properties	getQuestionProperties	読み取り専用
質問	import_question	importQuestion	書き込み（制限あり）；base64 .lsq
質問	delete_question	deleteQuestion	書き込み（制限あり、確認が必要）
質問	set_question_properties	setQuestionProperties	書き込み（制限あり）
回答	get_summary	getResponseSummary	読み取り専用
回答	list_response_exports	listResponseExportFormats	読み取り専用の形式検出（プラグイン対応）
回答	export_responses	exportResponses	読み取り専用のエクスポート
回答	add_response	addResponse	書き込み（制限あり）
回答	update_response	updateResponse	書き込み（制限あり）
回答	delete_response	deleteResponse	書き込み（制限あり、確認が必要）
回答	get_response_ids	getResponseIds	読み取り専用
回答	export_responses_by_token	exportResponsesByToken	読み取り専用のエクスポート
回答	export_timeline	exportTimeline	読み取り専用の集計件数
ファイル	upload_file	uploadFile	書き込み（制限あり）
ファイル	get_uploaded_files	listUploadedFiles	読み取り専用
参加者／トークン	add_participants	addParticipant, addMultipleParticipants	書き込み（制限あり）
参加者／トークン	list_participants	listParticipants, listFilteredParticipants	読み取り専用
参加者／トークン	get_participant_properties	getParticipantProperties	読み取り専用
参加者／トークン	delete_participants	deleteParticipants	書き込み（制限あり、確認が必要）
参加者／トークン	invite_participants	inviteParticipants	書き込み（制限あり、メール／通知）
参加者／トークン	remind_participants	remindParticipants	書き込み（制限あり、メール／通知）
割り当て	get_quota_properties	getQuotaProperties	読み取り専用；全件一覧取得のラッパーなし
割り当て	add_quota	addQuota	書き込み（制限あり）
割り当て	set_quota_properties	setQuotaProperties	書き込み（制限あり）
割り当て	delete_quota	deleteQuota	書き込み（制限あり、確認が必要）
言語	add_language	addSurveyLanguage	書き込み（制限あり）
言語	delete_language	deleteSurveyLanguage	書き込み（制限あり、確認が必要）
言語	set_language_properties	setSurveyLanguageProperties	書き込み（制限あり）
サイト設定	get_site_settings	getAvailableLanguages	読み取り専用
環境で READONLY_MODE=true が設定されている場合、上記の「書き込み（保護対象）」としてマークされたすべてのツールは、LimeSurvey を呼び出さずに明確なエラーメッセージを返します。

アンケート管理

listSurveys

認証済みユーザーがアクセス権を持つすべてのアンケートを一覧表示します。

パラメーター：なし

戻り値：

• 次のプロパティを持つアンケートオブジェクトの配列：
  • sid：アンケート ID
  • surveyls_title：アンケートのタイトル
  • active：アンケートが有効かどうか（「Y」または「N」）
  • expires：有効期限（設定されている場合）
  • startdate：開始日（設定されている場合）
  • その他のアンケートメタデータ

応答例：

[
  {
    "sid": "123456",
    "surveyls_title": "Customer Satisfaction Survey",
    "active": "Y",
    "expires": null,
    "startdate": "2023-01-01 00:00:00"
  },
  {
    "sid": "789012",
    "surveyls_title": "Employee Feedback",
    "active": "N",
    "expires": "2023-12-31 23:59:59",
    "startdate": "2023-06-01 00:00:00"
  }
]

getSurveyProperties

特定のアンケートの詳細なプロパティを取得します。

パラメーター：

• surveyId：プロパティを取得するアンケートの ID

戻り値：

• 設定、構成、メタデータなどのアンケートプロパティを含むオブジェクト

activateSurvey

現在無効になっているアンケートを有効にします。

パラメーター：

• surveyId：有効にするアンケートの ID

戻り値：

• 有効化処理の結果

getSurveyLanguageProperties

アンケートの言語固有のプロパティを取得します。

パラメーター：

• surveyId：アンケートの ID
• language：言語コード

戻り値：

• アンケートの言語固有のプロパティを含むオブジェクト

getAvailableLanguages

LimeSurvey のインストール環境で利用可能な言語を取得します。

パラメーター：なし

戻り値：

• 利用可能な言語コードとその名称のリスト

getSurveyLanguages

特定のアンケートで利用可能な言語を取得します。

パラメーター：

• surveyId：アンケートの ID

戻り値：

• アンケートで利用可能な言語コードの配列

getQuotaProperties

特定のクオータのプロパティを取得します。

このツールは get_quota_properties RemoteControl メソッドをラップします： get_quota_properties($sessionKey, $iQuotaId, $aQuotaSettings = null, $sLanguage = null). この MCP サーバーでは、アンケートのすべてのクオータの一覧表示はサポートされていません。

パラメーター：

• quotaId：特定のクオータ ID（必須）
• language（任意）：クオータの説明に使用する言語

戻り値：

• 指定されたクオータ ID のクオータ情報

addQuota

アンケートに新しいクオータを追加します。

パラメーター：

• surveyId：アンケートの ID
• name：クオータ名
• limit：クオータの回答数上限

戻り値：

• 作成されたクオータデータを含む LimeSurvey の結果オブジェクト

setQuotaProperties

既存のクオータのプロパティを更新します。

パラメーター：

• quotaId：更新するクオータの ID
• properties：更新するクオータフィールドを含むオブジェクト（例：name、limit、active、action、message、url）

戻り値：

• 更新されたクオータを説明する結果オブジェクト

deleteQuota

既存のクオータを削除します。

パラメーター：

• quotaId：削除するクオータの ID

戻り値：

• クオータが正常に削除されたかどうかを示す結果オブジェクト

addSurveyLanguage

アンケートに新しい言語を追加します。

パラメーター：

• surveyId：アンケートの ID
• language：追加する言語コード（例："de"、"fr"）

戻り値：

• 言語追加に関する LimeSurvey の結果オブジェクト

deleteSurveyLanguage

アンケートから言語を削除します。

パラメーター：

• surveyId：アンケートの ID
• language：削除する言語コード

戻り値：

• 言語が削除されたかどうかを示す結果オブジェクト

setSurveyLanguageProperties

アンケートの言語に固有のプロパティを設定します。

パラメーター：

• surveyId：アンケートの ID
• language（任意）：言語コード。基本言語を対象とする場合は省略します
• localeData：更新するロケールフィールドを含むオブジェクト（例：surveyls_title、surveyls_description、surveyls_welcometext）

戻り値：

• 更新された言語プロパティを説明する結果オブジェクト

setSurveyProperties

アンケートのプロパティを設定します。

このツールは、RemoteControl メソッド set_survey_properties をラップします： set_survey_properties($sessionKey, $iSurveyID, $aSurveyData)。一部のフィールド（たとえば sid、active、language、additional_languages、および有効化済みアンケートの一部のフィールド）は変更できず、LimeSurvey によって無視されます。

パラメーター：

• surveyId：アンケートの ID
• properties：更新するアンケートフィールドのオブジェクト

戻り値：

• 正常に更新されたフィールドを示す結果オブジェクト

質問の管理

listQuestions

指定したアンケートのすべての質問を一覧表示します。

パラメーター：

• surveyId：アンケートの ID
• groupId（省略可）：このグループの質問のみを取得します
• language（省略可）：質問テキストの言語

戻り値：

• ID、テキスト、タイプ、その他の設定などのプロパティを含む質問オブジェクトの配列

listQuestionGroups

指定したアンケートのすべての質問グループを一覧表示します。

パラメーター：

• surveyId：アンケートの ID
• language（省略可）：グループテキストの言語

戻り値：

• ID、タイトル、説明、順序などのプロパティを含む質問グループオブジェクトの配列

addGroup

アンケートに空の質問グループを作成します。RemoteControl の add_group をラップし、新しいグループ ID（成功時は整数）を返します。この ID を importQuestion の groupId として渡します。

パラメーター：

• surveyId：アンケート ID
• title：グループのタイトル
• description（省略可）：グループの説明。デフォルトは空文字列です

importQuestion

base64 エンコードされた .lsq データから質問をグループにインポートします。.lss を使う importSurvey と同じ考え方です。テンプレートを準備して（例：LimeSurvey からタイプごとに質問を 1 つずつエクスポートしておき）、異なるペイロードでこのツールを繰り返し呼び出します。

パラメーター：

• surveyId、groupId：対象のアンケートとグループ
• importData：base64 エンコードされた .lsq の内容
• importDataType：lsq である必要があります（デフォルト）
• mandatory：Y または N（デフォルトは N）
• newQuestionTitle、newQuestionText、newQuestionHelp（省略可）：インポート後に、対応する RemoteControl の省略可能な引数を上書きします

戻り値：成功時は新しい質問 ID（整数）、失敗時は LimeSurvey のエラー構造です。

deleteGroup

アンケートから質問グループを削除します。RemoteControl の delete_group をラップします。通常、グループ内の質問も削除されます。ご利用のインスタンスで確認してください。

パラメーター：

• surveyId、groupId：削除するアンケートとグループ
• confirmDeletion：true である必要があります（安全ガード）

deleteQuestion

qid で指定した質問を 1 つ削除します。RemoteControl の delete_question をラップします。複雑なタイプ（例：ランキング）では、listQuestions に追加の行（サブ質問）が表示される場合があります。エクスポート／インポートのサイクルで作成された内容に応じて、削除または再構築してください。

パラメーター：

• questionId：削除する質問の ID
• confirmDeletion：true である必要があります

getQuestionProperties

指定した質問のプロパティを取得します。

パラメーター：

• questionId：質問の ID
• language（省略可）：質問テキストの言語
• properties（省略可）：取得するプロパティ名の配列

戻り値：

• 質問の指定されたプロパティを含むオブジェクト

setQuestionProperties

RemoteControl の set_question_properties を介して、質問の書き込み可能なフィールドを更新します。最初に情報を取得してください： getQuestionProperties を呼び出し（必要に応じて設定名のリストを指定）、LimeSurvey が受け付けるキーだけを送信します。API では、qid、gid、sid、parent_qid、type、language などの構造フィールドの変更はブロックされます。

よくある編集

• question：質問文（多くの場合、HTML です）。
• help：質問文の下に表示されるヘルプテキスト。
• ベース言語以外のアンケート言語を更新する場合は、language を渡してください。

ランキング質問（type R）
回答者に表示される順位ラベルは通常、サブ質問行にあります（parent_qid が親を指します）。その行の qid に対して setQuestionProperties を使い、各サブ質問の question テキストを更新するか、.lsq テンプレートを編集して再インポートしてください。

リスト／コメント付きリスト形式
メインのプロンプトは引き続き親の question／help にあります。回答ラベルが別の回答レコードにある場合もあります。RemoteControl で必要な項目を取得できない場合は、選択肢リストには .lsq テンプレートを編集して importQuestion（または管理 UI）を使う方法を優先し、API で許可されている文言の調整にはこのツールを使ってください。

回答の管理

getResponseSummary

アンケートで収集された回答の概要情報を取得します。

パラメーター：

• surveyId：アンケートの ID

戻り値：

• 回答数とステータスに関する情報を含む概要オブジェクト

listResponseExportFormats

プラグインが提供する形式を含む、利用可能な回答エクスポート形式をグローバルに一覧表示します。

パラメーター：

• なし

戻り値：

• エクスポート形式オブジェクトのリスト。各オブジェクトには以下が含まれます：
  • type
  • pluginClass
  • label（null 可）
  • tooltip（null 可）
  • onclick（null 可）
  • isDefault（ブール値）

exportResponses

指定した形式でアンケートの回答をエクスポートします。

パラメーター：

• surveyId：アンケートの ID
• documentType：エクスポート形式のタイプ（動的／プラグイン対応）。最初に listResponseExportFormats を呼び出してください。デフォルト：「csv」
• language（任意）：回答エクスポートの言語
• completionStatus：完了ステータスによるフィルター（'complete'、'incomplete'、'all'）。デフォルト：「all」
• headingType：見出しのタイプ（'code'、'full'、'abbreviated'）。デフォルト：「code」
• responseType：回答のタイプ（'short' または 'long'）。デフォルト：「short」
• fields（任意）：エクスポートするフィールド名の配列

戻り値：

• 成功の概要と生のエクスポートペイロード
• decodeOutput: true のテキスト形式では、デコード済みのプレビューも含まれます

最初に情報を取得するエクスポートのワークフロー

1. listResponseExportFormats を呼び出し、現在の LimeSurvey インスタンスが公開している有効な type 値を確認します。
2. 返された type（例：csv、json、またはカスタムプラグイン形式）を選びます。
3. その documentType を指定して exportResponses を呼び出します。

例：

tool: listResponseExportFormats
args: {}
---
tool: exportResponses
args:
  surveyId: "123456"
  documentType: "csv"

listResponses

特定のアンケートの回答 ID を一覧表示します。

パラメーター：

• surveyId：アンケートの ID
• start：開始する回答インデックス。デフォルト：0
• limit：返す回答数。デフォルト：10
• attributes（任意）：含める属性名の配列

戻り値：

• 回答 ID と、要求された属性の配列

参加者の管理

addParticipant

アンケートに参加者を追加します。

パラメーター：

• surveyId：アンケートの ID
• email：参加者のメールアドレス
• firstName（任意）：名
• lastName（任意）：姓
• language（任意）：言語コード
• usesLeft：参加者がアンケートにアクセスできる回数。デフォルト：1
• validFrom（任意）：有効開始日時（YYYY-MM-DD HH:mm:ss）
• validUntil（任意）：有効終了日時（YYYY-MM-DD HH:mm:ss）

戻り値：

• 生成されたトークンを含む参加者データ

listParticipants

特定のアンケートの参加者を一覧表示します。

パラメーター：

• surveyId：アンケートの ID
• start：参加者の開始インデックス。デフォルト：0
• limit：返す参加者の数。デフォルト：10
• unused：未使用のトークンのみを表示します。デフォルト：false
• attributes（任意）：含める属性名の配列

戻り値：

• 要求された属性を含む参加者オブジェクトの配列

getParticipantProperties

特定の参加者／トークンのプロパティを取得します。

パラメーター：

• surveyId：アンケートの ID
• tokenId：トークンの ID
• attributes（任意）：含める属性名の配列

戻り値：

• 指定した参加者のプロパティを含むオブジェクト

統計の管理

exportStatistics

グラフを含めるかどうかを指定して、アンケートの統計を PDF、Excel、または HTML 形式でエクスポートします。

パラメーター：

• surveyId：統計をエクスポートするアンケートの ID
• documentType：エクスポート形式。'pdf'、'xls'、または 'html'。デフォルト："pdf"
• language（任意）：統計のエクスポートに使用する言語（デフォルト：アンケートのデフォルト言語）
• includeGraphs：エクスポートにグラフを含めるかどうか（PDF の場合のみ適用）。デフォルト：false
• groupIds（任意）：統計に含める特定の質問グループ ID。単一の ID または ID の配列を指定できます

戻り値：

• 要求された形式の統計ファイルを含む Base64 エンコード文字列

使用例：

exportStatistics:
  surveyId: "123456"
  documentType: "pdf"
  includeGraphs: true

開発

このプロジェクトは以下を使用して構築されています：

• Node.js
• @modelcontextprotocol/sdk - MCP サーバー SDK
• TypeScript - 型安全性と最新の JavaScript 機能のため
• dotenv - 環境変数の管理のため
• Axios - LimeSurvey Remote API への HTTP リクエストのため

ビルド

npm run build

開発モード

npm run dev

ライセンス

MIT