Maximo Enterprise MCP

Production-focused IBM Maximo Asset Management integration for AI systems.

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.

The current stable surface is 31 public tools across assets, work orders, inventory, purchasing, labor, locations, reporting, schema discovery, and administration.

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 / Cursor

1. Create a virtual environment and install the package.

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
pip install .

2. Copy .env.example to .env and fill in your Maximo settings.

3. Use a local MCP config like .mcp.json.example or .cursor/mcp.json.example.

Example:

{
  "mcpServers": {
    "maximo": {
      "command": "python",
      "args": ["server.py"],
      "env": {
        "MAXIMO_URL": "https://your-maximo-host.example.com/maximo/oslc",
        "MAXIMO_HOST": "https://your-maximo-host.example.com",
        "AUTH_MODE": "basic",
        "MAXIMO_USERNAME": "your-maximo-username",
        "MAXIMO_PASSWORD": "your-maximo-password",
        "CURRENT_USER_ROLE": "readonly",
        "TRANSPORT_MODE": "stdio"
      }
    }
  }
}

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

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 selecte

... View full README on GitHub