MCP Server¶

AIMage SDK は、Model Context Protocol クライアント向けに optional な Search MCP server を提供します。

MCP 依存は optional extra に分けているため、通常の SDK インストールでは MCP runtime は入りません。

インストール¶

pip install "aimage[mcp]"

ローカル開発:

pip install -e ".[mcp]"

設定¶

MCP server は SearchClient と同じ認証情報を使います。

環境変数	用途
`AIMAGE_API_KEY`	API key。token より優先
`AIMAGE_SEARCH_TOKEN`	Bearer token
`AIMAGE_SEARCH_SERVICE`	`PROD`、`DEV`、`STAGING`、`LOCAL`、または custom URL
`AIMAGE_SEARCH_BASE_URL`	custom API origin。service より優先
`AIMAGE_MCP_TIMEOUT`	request timeout 秒数。default は `30`
`AIMAGE_MCP_TRANSPORT`	default transport。default は `stdio`
`AIMAGE_MCP_ENABLE_WRITE` / `AIMAGE_MCP_ENABLE_WRITES`	`1` / `true` で書き込み tool を公開
`AIMAGE_MCP_ENABLE_DELETE` / `AIMAGE_MCP_ENABLE_DELETES`	`1` / `true` で削除 tool を公開。write mode も必要
`AIMAGE_MCP_ENABLE_RAW_RPC`	`1` / `true` で raw ORPC passthrough を公開

実行¶

default transport は stdio です。

aimage-mcp-search

service を指定:

aimage-mcp-search --service DEV
aimage-mcp-search --base-url https://api.search.dev.ai-mage.jp

Streamable HTTP で実行:

aimage-mcp-search --transport streamable-http

書き込み tool は default では無効です。

aimage-mcp-search --enable-write

削除 tool には追加 flag が必要です。

aimage-mcp-search --enable-write --enable-delete

raw ORPC passthrough も opt-in です。

aimage-mcp-search --enable-raw-rpc

クライアント設定例¶

{
  "mcpServers": {
    "aimage-search": {
      "command": "aimage-mcp-search",
      "env": {
        "AIMAGE_API_KEY": "your_api_key",
        "AIMAGE_SEARCH_SERVICE": "DEV"
      }
    }
  }
}

Tools¶

read-only mode では health、project/video/clip の read、character/resource/reference-image/translation-table の read、novel search、agent read tool を公開します。

--enable-write を指定すると、project settings、clip update、character/resource/reference-image の create/update、translation table の create/update、generated image 保存、conversation branch tool も公開されます。削除 tool には --enable-delete も必要です。raw ORPC passthrough には --enable-raw-rpc が必要です。

Write mode

MCP クライアントは tool を agent に公開します。接続アカウントとプロジェクト権限が自動更新に適している場合だけ write mode を有効にしてください。

Python API¶

from aimage.mcp import SearchMCPConfig, create_search_mcp
from aimage.search.settings import SearchService

mcp = create_search_mcp(
    SearchMCPConfig(api_key="...", service=SearchService.DEV)
)
mcp.run()