MCP Server¶

AIMage SDK provides an optional Search MCP server for Model Context Protocol clients.

The MCP dependency is optional, so normal SDK installs do not pull in the MCP runtime.

Install¶

pip install "aimage[mcp]"

For local development:

pip install -e ".[mcp]"

Configuration¶

The MCP server uses the same authentication inputs as SearchClient.

Environment variable	Purpose
`AIMAGE_API_KEY`	API key, preferred over token
`AIMAGE_SEARCH_TOKEN`	Bearer token
`AIMAGE_SEARCH_SERVICE`	`PROD`, `DEV`, `STAGING`, `LOCAL`, or a custom URL
`AIMAGE_SEARCH_BASE_URL`	Custom API origin, preferred over service
`AIMAGE_MCP_TIMEOUT`	Request timeout in seconds, defaults to `30`
`AIMAGE_MCP_TRANSPORT`	Default transport, defaults to `stdio`
`AIMAGE_MCP_ENABLE_WRITE` / `AIMAGE_MCP_ENABLE_WRITES`	Set to `1` / `true` to expose mutating tools
`AIMAGE_MCP_ENABLE_DELETE` / `AIMAGE_MCP_ENABLE_DELETES`	Set to `1` / `true` to expose delete tools; write mode is also required
`AIMAGE_MCP_ENABLE_RAW_RPC`	Set to `1` / `true` to expose raw ORPC passthrough

Run¶

stdio is the default transport:

aimage-mcp-search

Select a service:

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

Run Streamable HTTP for local or remote debugging:

aimage-mcp-search --transport streamable-http

Mutating tools are disabled by default:

aimage-mcp-search --enable-write

Delete tools require an extra flag:

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

Raw ORPC passthrough is also opt-in:

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

Client Example¶

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

Tools¶

Read-only mode exposes health, project/video/clip readers, character/resource/reference-image/translation-table readers, novel search, and agent read tools.

With --enable-write, the server also exposes project settings, clip updates, character/resource/reference-image create/update tools, translation table create/update tools, generated-image saving, and conversation branch tools. Delete tools require --enable-delete as well. Raw ORPC passthrough requires --enable-raw-rpc.

Write mode

MCP clients expose tools to agents. Keep write mode disabled unless the connected account and project permissions are appropriate for automated mutations.

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()