Maximo Enterprise MCP

Maximo Enterprise MCP

A production-focused integration that brings IBM Maximo Asset Management into AI workflows through the Model Context Protocol.

Built by Maxis Technology as part of Alchemize — a state-of-the-art enterprise data management platform capable of doing in hours what others do in days. Want to know more? Head over to alchemize.io.

This project now exposes:

• A stable MCP server for Claude Desktop, Cursor, and other MCP clients.
• A hosted HTTP/SSE mode for remote MCP access.
• A FastAPI tool layer for OpenAI, Gemini, Grok, and custom orchestrators.

See CHANGELOG.md for the per-version release history (64 net-new tools across waves 1–9).

The current stable surface is 95 public tools across 21 categories. Every tool ships with a strict Pydantic input model (extra="forbid").

When a customer's Maximo doesn't have a particular vertical's data populated (no oil-and-gas turnarounds, no transportation fleet, no Spatial coordinates, etc.), every tool returns data_unavailable=True with a user-friendly note explaining what's missing and what an admin can do. Never a cryptic 400/404.

Maximo version compatibility

The integration suite (64 net-new tools across 8 wave smoke tests) is verified end-to-end against Maximo 7.6.x with the mxapi integration extensions (the API patch pack — mxapi* object structures published).

The codebase is defensively designed for cross-version use:

• Multi-candidate OS endpoints (tools/*.py constants like JP_OS_CANDIDATES, LABOR_OS_CANDIDATES) iterate mx* first then mxapi* and fall through 404s
• Single-condition WHERE + Python post-filter (defensive against the most restrictive build encountered — see compound_where_drops_connection)
• +field / -field orderBy direction prefix (strict OSLC v2 spec — works on every build)
• Graceful data_unavailable=True flag with admin-action note when an OSLC object structure isn't published on the customer's deployment

Every read tool returns a structured envelope (success / data / metadata). Tools that need data their Maximo build doesn't expose surface a data_unavailable: true flag with an admin-action note rather than failing silently. Write tools ship # DISABLED by default.

Quick-start prompts

Once connected to Claude Desktop / Cursor / Code, try:

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?

Responsible Use

This server speaks to a live IBM Maximo instance and exposes its data — and, when explicitly enabled, its mutating operations — to a language model. Before deploying:

• Run hosted HTTP/SSE behind an authenticated gateway. Per-request identity comes from MCP_AUTH_MODE=jwt (OIDC) or static + gateway-injected X-MCP-* headers. Never expose the FastAPI tool API to untrusted callers without an identity solution in front.
• TLS at the edge (or in-process via MCP_SSL_*) is mandatory for any non-stdio deployment. The app does not terminate TLS itself.
• Keep all write tools # DISABLED in server.py until you have reviewed the RBAC policy and audit posture for your environment.
• Stamp MAXIMO_ENV=dev|staging|prod per deployment so audit records and /healthz make it obvious which Maximo a container is talking to.
• Read SECURITY.md and PRODUCT_GAPS_BEFORE_DEPLOY.md before pushing to a public registry; the latter documents the exact controls required for https://github.com/mcp-style listings.

Architecture

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

Installation

Local MCP for Claude Desktop / Claude Code / Cursor

You have two ways to install: uvx (recommended — no manual install) or pip install.

Option A — uvx (recommended)

Install uv once, then point your MCP client at uvx maximo-enterprise-mcp. uvx downloads, caches, and runs the package on demand.

Option B — pip install

pip install maximo-enterprise-mcp

Then in the configs below, replace:

"command": "uvx",

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

with:

"command": "maximo-enterprise-mcp",

"args": []

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/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" } } } }

Restart Claude Desktop. The hammer icon appears once tools load.

Claude Code

Add to project-level .mcp.json or global ~/.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" } } } }

Run /mcp in Claude Code to verify the connection.

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{

"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" } } } }

In Cursor: Settings → MCP → Refresh to load.

Hosted MCP over HTTP/SSE

Hosted mode is intended for trusted network or gateway-protected deployments. It now fails closed unless MCP_ACCESS_TOKEN is set.

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

Remote MCP clients should connect to:

• MCP SSE endpoint: http://host:8080/sse
• Health endpoint: http://host:8080/healthz

Example remote MCP config:

{

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

FastAPI Tool API

Hosted HTTP mode also exposes a tool API for non-MCP platforms:

• 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

Example invocation:

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 Platform Usage

OpenAI

Use GET /v1/providers/openai-tools to retrieve OpenAI-compatible tool definitions, then execute the selected tool via POST /v1/tools/{tool_name}.

Gemini

Use GET /v1/providers/gemini-tools to retrieve Gemini function declarations from the same shared tool registry.

Grok

Use GET /v1/providers/grok-tools. The payload is OpenAI-compatible so the same orchestration pattern works.

Optio