Maximo Enterprise MCP

Maximo Enterprise MCP

Model Context Protocolを通じてIBM Maximo Asset ManagementをAIワークフローに取り込む、実運用を重視した統合機能です。

Maxis Technologyが、Alchemizeの一環として開発しました。Alchemizeは、ほかの製品なら数日かかる作業を数時間で実行できる、最先端のエンタープライズデータ管理プラットフォームです。詳しくはalchemize.ioをご覧ください。

このプロジェクトでは、以下を提供しています。

• Claude Desktop、Cursor、その他のMCPクライアント向けの安定したMCPサーバー。
• リモートMCPアクセス向けの、ホスト型HTTP/SSEモード。
• OpenAI、Gemini、Grok、およびカスタムオーケストレーター向けのFastAPIツールレイヤー。

バージョンごとのリリース履歴については、CHANGELOG.mdをご覧ください（wave 1～9で新たに追加されたツールは合計64個です）。

現在の安定版では、21のカテゴリにわたる95個の公開ツールを提供しています。すべてのツールに、厳密なPydantic入力モデル（extra="forbid"）が付属します。

顧客のMaximoに特定の業種のデータ（石油・ガスのターンアラウンド、輸送車両群、Spatialの座標など）が登録されていない場合、すべてのツールはdata_unavailable=Trueを返し、不足しているデータと管理者が実行できる対応を説明するわかりやすいメモを表示します。原因のわからない400/404エラーが返ることはありません。

Maximoのバージョン互換性

統合スイート（8回のwaveスモークテストで検証した、新たに追加された64個のツール）は、mxapi統合拡張機能（APIパッチパック。mxapi*オブジェクト構造が公開された環境）を備えたMaximo 7.6.xで、エンドツーエンドの動作を検証済みです。

Maximoビルド	ステータス	備考
mxapi拡張機能を備えたMaximo 7.6.x	✅ 実環境で検証済み（8回のwaveスモークテストがすべて約3.5分で合格）	テスト対象の構成
mxapi拡張機能のないMaximo 7.6.x	✅ 動作する見込みです	複数候補のmx*からmxapi*への切り替えが、適切にmx*パスへフォールバックします
MAS 8.x（RHOCP上のManage）	⚠️ 動作する見込みですが、未テストです	mx*とmxapi*の両方が公開されています。MAS SSOでは認証フローにMCP_AUTH_MODE=jwtが必要な場合があります
MAS 9.x（RHOCP上のManage）	⚠️ 動作する見込みですが、未テストです	mxapi*が優先されます。認証に関する注意点は同じです

このコードベースは、異なるバージョンでも使えるよう防御的に設計されています。

• 複数候補のOSエンドポイント（tools/*.pyのJP_OS_CANDIDATES、LABOR_OS_CANDIDATESなど）は、まずmx*を試し、次にmxapi*を試して、404の場合は次の候補に進みます
• 単一条件のWHERE句とPythonによる後処理（これまでに遭遇した最も制約の厳しいビルドへの対策です。詳細はcompound_where_drops_connectionを参照してください）
• +field / -fieldによるorderBy方向の接頭辞（厳密なOSLC v2仕様に準拠しており、すべてのビルドで動作します）
• 顧客環境でOSLCオブジェクト構造が公開されていない場合は、管理者の対応を記載したメモとともにdata_unavailable=Trueフラグを返します | カテゴリ | ツール数 | 提供内容 | |---|---:|---| | 資産 | 9 | ライフサイクル、履歴、ダウンタイム／MTTR／MTBF、検索、重要度マトリックス、保証期間別分類、故障クラス階層、メーター読み取り値 | | 作業指示書 | 8 | 一覧／取得／KPI、タスク内訳、計画と実績の差異、コスト内訳、スケジュールカレンダー、「自分に割り当てられた作業指示書」 | | 作業計画 | 3 | カタログ一覧、タスク／作業員／資材／ツールを含む完全な計画、作業計画に基づくコスト見積もり | | サービスリクエスト | 2 | 作業指示書の前段階となる受付の一覧＋取得 | | 在庫 | 8 | 在庫確認、在庫不足一覧、再発注推奨、品目マスター、保管場所カタログ、総評価額、重要予備品のリスク | | 購買 | 6 | 発注書（一覧＋取得）、購買依頼、ベンダー（一覧＋パフォーマンス）、ベンダー／ステータス／作業種別ごとの支出分析 | | 作業員 | 5 | 作業員／クルー／技能の一覧、稼働率、対応可能な技術者の検索（空きが最も多い順） | | ロケーション | 3 | 一覧＋取得＋階層ツリー | | レポート | 6 | 保全 KPI ダッシュボード、故障パレート図、問題資産、Excel＋PDF エクスポート、Carbon HTML テーブル | | AI インテリジェンス | 4 | 自然言語から OSLC への変換、異常検知（>2σ）、根本原因の提案、資産健全性スコア | | AI の優位性 (Wave 8) | 6 | 作業指示書の要約、故障の自動分類、資産とのチャット、予防保全の最適化、故障発生期間の予測、ランブックの生成 — すべてのツールで LLM による拡張機能を利用でき、統計ベース／ルールベースのフォールバックも備えています | | 空間／GIS (Wave 9) | 2 | 緯度／経度付近の資産検索、技術者の最適ルート検索 — 座標が登録されていない場合は「Spatial not installed」に適切にフォールバックします | | コンプライアンスと EHS | 6 | 校正／検査／許可／認証期限切れ／インシデント／コンプライアンスダッシュボード | | 製薬 | 3 | 校正監査証跡（FDA）、クリーンルーム資産、GxP リスクスコア | | 石油・ガス | 3 | ターンアラウンド状況、圧力容器の検査、吊り上げ作業台帳 | | 製造 | 3 | OEE（稼働率）、生産ラインの状況、段取り替え（SMED）の作業指示書 | | 公益事業 | 3 | 停電の影響分析、電力網ゾーンの資産、SAIDI／SAIFI の代替指標 | | ヘルスケア | 3 | 医療機器の予防保全期限、機器のライフサイクル（NEW/STABLE/AGING/EOL）、JC 医療環境安全 | | 輸送 | 3 | 車両群の稼働準備率、走行距離に基づく予防保全期限、急増検知機能付き燃料消費傾向 | | スキーマ／管理 | 8 | オブジェクト構造の検出、スキーマ詳細、OSLC クエリの検証、コード生成、ユーザー、監査ログ、イベントサブスクリプション | | コア | 1 | health_check — 接続プローブ＋ツール数 |

すべての読み取りツールは、構造化されたエンベロープ（success / data / metadata）を返します。Maximo のビルドで公開されていないデータが必要なツールは、何も通知せずに失敗するのではなく、管理者の対応に関する注記とともに data_unavailable: true フラグを返します。書き込みツールは、デフォルトで # DISABLED の状態で提供されます。

クイックスタートプロンプト

接続したら、Claude Desktop／Cursor／Code で次をお試しください。

Use maximo mcp. Asset 1001 isn't behaving — pull its details, recent work-order
history, and meter readings for the last 90 days.

Use maximo mcp. Run the compliance dashboard for site BEDFORD, then list the top
5 bad-actor assets and any calibrations overdue right now.

Use maximo mcp. I'm new to BEDFORD as planner — show me what job plans we have,
estimate cost for one, and find me an available welder.

Use maximo mcp. QBR slides due Friday. Export work orders to Excel + asset
report to PDF, plus the maintenance KPI dashboard for the cover slide.

Use maximo mcp. Quarterly EHS review — run compliance dashboard, list calibrations
due in 90 days, and certifications expiring in 60.

Use maximo mcp. Pump 1001 has been intermittent. Predict its next failure window,
recommend whether we should tune its PM frequency, and generate a runbook for the
last "grinding noise" complaint based on what we did before.

Use maximo mcp. Summarize WO 6540 for tomorrow's shift handover, then auto-classify
the failure code from this complaint: "intermittent grinding noise during operation".

Use maximo mcp. Chat with asset 1001: when did it last fail, what was the root cause,
and how often does it break?

責任ある使用

このサーバーは稼働中の IBM Maximo インスタンスと通信し、そのデータを言語モデルに公開します。また、明示的に有効化した場合は、データを変更する操作も公開します。デプロイする前に、次の点を確認してください。

• ホスト型 HTTP/SSE は、認証済みゲートウェイの背後で実行してください。リクエストごとの認証情報は、MCP_AUTH_MODE=jwt（OIDC）または静的ヘッダーとゲートウェイによって挿入される X-MCP-* ヘッダーから取得します。手前に認証ソリューションを設けずに、FastAPI ツール API を信頼できない呼び出し元に公開しないでください。
• stdio 以外でデプロイする場合、エッジでの TLS（または MCP_SSL_* によるプロセス内 TLS）が必須です。このアプリ自体は TLS を終端しません。
• ご利用環境の RBAC ポリシーと監査体制を確認するまでは、server.py のすべての書き込みツールを # DISABLED のままにしてください。
• デプロイごとに MAXIMO_ENV=dev|staging|prod を設定し、監査記録と /healthz から、コンテナーがどの Maximo と通信しているかが明確にわかるようにしてください。
• 公開レジストリにプッシュする前に、SECURITY.md と PRODUCT_GAPS_BEFORE_DEPLOY.md をお読みください。後者には、https://github.com/mcp のようなリスティングに必要な具体的な制御事項が記載されています。

アーキテクチャ

Local MCP clients        -> stdio MCP server -> Maximo OSLC
Remote MCP clients       -> HTTP gateway -> hosted MCP SSE -> Maximo OSLC
OpenAI / Gemini / Grok   -> FastAPI tool API -> shared executor -> Maximo OSLC

インストール

Claude Desktop／Claude Code／Cursor 向けローカル MCP

インストール方法は 2 つあります。uvx（推奨。手動インストール不要）または pip install です。

オプション A — uvx（推奨）

uv を一度インストールしたら、MCP クライアントで uvx maximo-enterprise-mcp を指定します。uvx はパッケージをオンデマンドでダウンロード、キャッシュ、実行します。

オプション B — pip install

pip install maximo-enterprise-mcp

次に、以下の設定で次の箇所を置き換えます。

"command": "uvx",
"args": ["maximo-enterprise-mcp"]

置き換え後：

"command": "maximo-enterprise-mcp",
"args": []

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json（Windows）または ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）を編集します。

{
  "mcpServers": {
    "maximo": {
      "command": "uvx",
      "args": ["maximo-enterprise-mcp"],
      "env": {
        "MAXIMO_URL": "https://your-maximo-host.com/maximo/oslc",
        "MAXIMO_HOST": "https://your-maximo-host.com",
        "AUTH_MODE": "basic",
        "MAXIMO_USERNAME": "your-username",
        "MAXIMO_PASSWORD": "your-password",
        "CURRENT_USER_ROLE": "readonly"
      }
    }
  }
}

Claude Desktop を再起動します。ツールが読み込まれると、ハンマーアイコンが表示されます。

Claude Code

プロジェクトレベルの .mcp.json またはグローバルの ~/.claude.json に追加します。

{
  "mcpServers": {
    "maximo": {
      "command": "uvx",
      "args": ["maximo-enterprise-mcp"],
      "env": {
        "MAXIMO_URL": "https://your-maximo-host.com/maximo/oslc",
        "MAXIMO_HOST": "https://your-maximo-host.com",
        "AUTH_MODE": "basic",
        "MAXIMO_USERNAME": "your-username",
        "MAXIMO_PASSWORD": "your-password",
        "CURRENT_USER_ROLE": "readonly"
      }
    }
  }
}

Claude Code で /mcp を実行し、接続を確認します。

Cursor

~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）に追加します。

{
  "mcpServers": {
    "maximo": {
      "command": "uvx",
      "args": ["maximo-enterprise-mcp"],
      "env": {
        "MAXIMO_URL": "https://your-maximo-host.com/maximo/oslc",
        "MAXIMO_HOST": "https://your-maximo-host.com",
        "AUTH_MODE": "basic",
        "MAXIMO_USERNAME": "your-username",
        "MAXIMO_PASSWORD": "your-password",
        "CURRENT_USER_ROLE": "readonly"
      }
    }
  }
}

Cursor で「Settings → MCP → Refresh」を選択して読み込みます。

HTTP/SSE 経由のホスト型 MCP

ホスト型モードは、信頼できるネットワークまたはゲートウェイで保護されたデプロイを想定しています。現在は、MCP_ACCESS_TOKEN が設定されていない場合、フェイルクローズします。

python server.py --http --host 0.0.0.0 --port 8080

リモート MCP クライアントは、次のエンドポイントに接続してください。

• MCP SSE エンドポイント：http://host:8080/sse
• ヘルスチェックエンドポイント：http://host:8080/healthz

リモート MCP の設定例：

{
  "mcpServers": {
    "maximo": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer <your MCP_ACCESS_TOKEN>"
      }
    }
  }
}

FastAPI ツール API

ホスト型 HTTP モードでは、MCP 以外のプラットフォーム向けにツール API も公開されます。

• GET /healthz
• GET /v1/tools
• POST /v1/tools/{tool_name}
• GET /v1/providers/openai-tools
• GET /v1/providers/gemini-tools
• GET /v1/providers/grok-tools

呼び出し例：

curl -X POST http://localhost:8080/v1/tools/list_assets \
  -H "Authorization: Bearer $MCP_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"site_id\":\"BEDFORD\",\"page_size\":10}"

AI プラットフォームでの使用方法

OpenAI

GET /v1/providers/openai-tools を使用して OpenAI 互換のツール定義を取得し、選択したツールを POST /v1/tools/{tool_name} で実行します。

Gemini

GET /v1/providers/gemini-tools を使用して、共通のツールレジストリから Gemini の関数宣言を取得します。

Grok

GET /v1/providers/grok-tools を使用します。ペイロードは OpenAI 互換のため、同じオーケストレーションパターンを利用できます。

オプションの依存関係

コアのインストールでは requirements.txt を使用します。

オプションの追加機能は pyproject.toml で定義されています。

• OpenAI、ChromaDB、sentence-transformers を使用するには pip install ".[ai]"。
• Excel および PDF のエクスポート依存関係を使用するには pip install ".[exports]"。
• ローカルでのテストおよびリンティングツールを使用するには pip install ".[dev]"。

環境変数

すべての項目については .env.example を参照してください。特に重要な変数は次のとおりです。

変数	必須	説明
MAXIMO_URL	はい	Maximo OSLC のベース URL 全体
MAXIMO_HOST	はい	Maximo ホストのルート URL
AUTH_MODE	はい	basic、apikey、または oauth
MAXIMO_USERNAME / MAXIMO_PASSWORD	Basic 認証	Maximo の認証情報
MCP_ACCESS_TOKEN	ホスト型 HTTP	ホスト型 MCP/API モードに必須のベアラートークン
CURRENT_USER_ROLE	ローカルのみ	ローカルまたは信頼されたデプロイでのセッションロール
REDIS_URL	いいえ	Redis キャッシュ接続文字列
VPN_SAFE_MODE	いいえ	より安全なデフォルトのペイロードサイズを有効にします
DEFAULT_PAGE_SIZE	いいえ	セーフモード有効時のデフォルトのページサイズ

Docker

ビルド

docker build -t maximo-enterprise-mcp .

実行

docker run -d ^
  -p 8080:8080 ^
  -e TRANSPORT_MODE=http ^
  -e MCP_ACCESS_TOKEN=change-me ^
  -e MAXIMO_URL=https://your-maximo-host.example.com/maximo/oslc ^
  -e MAXIMO_HOST=https://your-maximo-host.example.com ^
  -e AUTH_MODE=basic ^
  -e MAXIMO_USERNAME=your-maximo-username ^
  -e MAXIMO_PASSWORD=your-maximo-password ^
  maximo-enterprise-mcp

Redis も含める場合は docker-compose.yml を使用します。

デプロイに関するガイダンス

このサーバー自体は TLS を終端しません。stdio 以外でデプロイする場合は、 エッジ側、または MCP_SSL_CERTFILE／MCP_SSL_KEYFILE を使用してプロセス内で 必ず TLS を終端してください。SECURITY.md を参照してください。

AWS

• 最初のデプロイ先として、ECS Fargate または App Runner を推奨します。
• シークレットは AWS Secrets Manager に保存してください。
• 必須： TLS とアクセス制御のため、前段に ALB または API Gateway を配置してください。
• 可能な場合は、Maximo への接続をプライベートに保ってください。

Azure

• 最初のデプロイ先として、Azure Container Apps または App Service を推奨します。
• シークレットは Key Vault に保存してください。
• 必須： TLS とアクセス制御のため、前段に Application Gateway または Front Door を配置してください。

環境の分離

1 つのコンテナイメージを、3 つのデプロイメントと 3 つのシークレットストアで実行します。デプロイメントごとに MAXIMO_ENV=dev|staging|prod を設定します。この値はすべての 監査記録と /healthz に記録されるため、オペレーターは各コンテナがどの Maximo を参照しているかをすぐに確認できます。

推奨パターン：

デプロイメント	MAXIMO_ENV	Maximo の接続先	トークンのスコープ
dev	dev	dev Maximo	dev MCP_ACCESS_TOKEN／OIDC テナント
staging	staging	staging Maximo	staging トークン／OIDC テナント
prod	prod	prod Maximo	prod トークン／OIDC テナント

環境間でトークンを決して使い回さないでください。漏えいした dev トークンで prod のロックを解除できてはならず、誤った接続先にルーティングされた dev コンテナが prod のデータに書き込んではなりません。

パブリックインターネット

ホストされた MCP をそのままパブリックインターネットに公開するには、以下のすべてが必要です。例外はありません。

• インバウンド認証（ベアラーまたは OIDC）（MCP_AUTH_MODE）
• エッジまたはプロセス内での TLS（アプリはデフォルトで平文を提供します）
• 明示的な CORS 許可リスト（MCP_ALLOWED_ORIGINS）。* は使用しないでください
• レート制限（RATE_LIMIT_PER_MINUTE）と、これとは別のエッジ側レート制限
• 耐久性のある転送先への監査ログ記録
• プライベートな Maximo 接続、または厳格なネットワーク制御

開発

単体テストの実行

pytest -m "not integration"

統合テストの実行

統合テストは、.env で設定された実際の Maximo インスタンスに接続します。テストスイートは 2 つあります。

• tests/integration_test_tools.py — 稼働中の単一の Maximo に対して、ツールごとのスモークテストを実行します
• tests/integration/test_smoke_wave[1-4].py — ウェーブ 1～4／6 で追加されるすべての公開ツールをゲートする、ウェーブごとのスモークテストを実行します

# Run every integration test (skipped automatically if MAXIMO_URL is unset)
pytest tests/integration -m integration -v

# Run a single wave's smoke
pytest tests/integration/test_smoke_wave2.py -m integration -v

# Or run a wave standalone for ad-hoc debugging
python tests/integration/test_smoke_wave2.py

登録済み MCP ツールの一覧表示

python server.py --test

セキュリティに関する注意事項

• 実際の .env、.mcp.json、または .cursor/mcp.json の値をコミットしないでください。
• *.example ファイルのサンプル設定を使用し、シークレットはローカル専用ファイルまたはシークレットマネージャーに保管してください。
• ホストモードでは MCP_ACCESS_TOKEN が必要です。
• 環境変数ベースのロールモデルは、ローカルまたは信頼されたデプロイメントには適していますが、マルチテナントのパブリックホスティングには適していません。

---

IBM および Maximo は International Business Machines Corp. の商標であり、ここでは説明目的でのみ使用しています。このプロジェクトは IBM と提携していません。