IBM Maximo

🎯 What is This?

The Maximo MCP Server is a Model Context Protocol server that connects AI assistants (like Antigravity, Cursor, or VS Code Copilot) directly to your IBM Maximo environment. Instead of manually copying API documentation, the AI can:

📚 Documentation

Core Guides

French Translations

Word Documents

All guides are also available in .docx format in the docs/ folder for offline reading and sharing.

⚡ Quick Start

Prerequisites

• Node.js v18 or higher
• Maximo API Key with read access
• AI IDE with MCP support (Antigravity, Cursor, VS Code + Continue)

Installation

Installation

Method 1: Run directly with npx (Recommended)

npx maximo-mcp-server

Method 2: Clone from Source

# Clone the repositorygit clone https://github.com/markusvankempen/maximo-mcp-ai-integration-options.gitcd maximo-mcp-ai-integration-options
# Install dependenciesnpm install
# Set up environment variablescp .env.example .env# Edit .env with your Maximo credentials

Environment Configuration

Edit the .env file with your Maximo credentials:

# .env (never commit this file!)MAXIMO_URL=https://your-maximo-host.com/maximo/apiMAXIMO_HOST=https://your-maximo-host.comMAXIMO_API_KEY=your-api-key-hereMAXIMO_OPENAPI_PATH=./maximo_openapi.jsonPORT=3002

Download the OpenAPI Schema (Recommended)

The OpenAPI schema file enables offline schema lookups for faster AI responses:

# Download from your Maximo instancecurl -X GET "https://your-maximo-host.com/maximo/oslc/oas/api" \     -H "apikey:your-api-key-here" \     -o maximo_openapi.json

Alternatively, download via Swagger UI at: https://your-host/maximo/oslc/oas/api.html (Click "Explore" or "Download")

Method 3: Direct Browser Download (Manual)

If curl fails (e.g., due to SSL/network errors), you can manually download the file:

1. Open this URL in your browser: https://[YOUR_MAXIMO_HOST]/maximo/oslc/oas/api (Replace [YOUR_MAXIMO_HOST] with your actual server address)

2. You may be prompted to log in to Maximo.

3. Once the JSON loads, right-click the page and select "Save Page As...".

4. Save the file as maximo_openapi.json in your project root folder.

Note: This file is ~12MB and contains all Object Structure definitions for your Maximo instance.

IDE Configuration

VS Code with GitHub Copilot (Recommended)

Option 1: Install from the MCP Server Gallery

1. Enable chat.mcp.gallery.enabled in VS Code settings
2. Open the Extensions view (⇧⌘X)
3. Type @mcp maximo in the search field
4. Click Install to add the Maximo MCP server

Option 2: Add manually via mcp.json

1. Open the Command Palette (⇧⌘P) → MCP: Open Workspace Folder Configuration
2. Add the following configuration:

{  "inputs": [    {      "type": "promptString",      "id": "maximo-url",      "description": "Maximo REST API Base URL (e.g., https://your-host/maximo/api)"    },    {      "type": "promptString",      "id": "maximo-api-key",      "description": "Maximo API Key",      "password": true    },    {      "type": "promptString",      "id": "maximo-host",      "description": "Maximo Host URL (e.g., https://your-host)"    }  ],  "servers": {    "maximo-mcp-server": {      "type": "stdio",      "command": "npx",      "args": ["-y", "maximo-mcp-server"],      "env": {        "MAXIMO_URL": "${input:maximo-url}",        "MAXIMO_API_KEY": "${input:maximo-api-key}",        "MAXIMO_HOST": "${input:maximo-host}"      }    }  }}

3. VS Code will prompt you for your Maximo credentials when the server starts.

💡 Tip: This project includes a .vscode/mcp.json file. If you clone the repo, VS Code will auto-detect the MCP server configuration.

Google Antigravity (Manual Setup Required)

⚠️ Note: The Antigravity MCP Store is curated and does not auto-discover servers from the registry. You must add this server manually.

1. Open Antigravity
2. Click "..." dropdown at the top of the Agent panel
3. Select "MCP Servers" → "Manage MCP Servers" → "View raw config"
4. Add to your mcp_config.json:

{  "mcpServers": {    "maximo-mcp-server": {      "command": "npx",      "args": ["-y", "maximo-mcp-server"],      "env": {        "MAXIMO_URL": "https://your-maximo-host/maximo/api",        "MAXIMO_API_KEY": "your-api-key-here",        "MAXIMO_HOST": "https://your-maximo-host"      }    }  }}

5. Save and click Refresh

Cursor / Claude Desktop

# Copy the templatecp config/mcp_config.json.example ~/.cursor/mcp.json# Or for Claude Desktop:cp config/mcp_config.json.example ~/Library/Application\ Support/Claude/claude_desktop_config.json

Edit with your Maximo credentials:

{  "mcpServers": {    "maximo-mcp-server": {      "command": "npx",      "args": ["-y", "maximo-mcp-server"],      "env": {        "MAXIMO_URL": "https://your-maximo-host/maximo/api",        "MAXIMO_API_KEY": "your-api-key-here"      }    }  }}

Verify Connection

In your AI IDE, ask:

"Is the Maximo MCP server connected?"

The AI will call get_instance_details and confirm connectivity.

🎬 Live Demo

Asset Manager Application

We built a complete Maximo Asset Manager web application using only natural language prompts and the MCP server.

Demo Features

🎥 Screen Recording

A complete video demonstration is available: assets_demo_recording.webp

Try It Yourself

# Start the local proxy servernode server.js
# Open in browseropen http://localhost:3002/demos/assets.html

🛠 Available MCP Tools

The server exposes 9 tools to the AI — 6 read tools and 3 write/CRUD tools:

[MCP Tools UI]

Read Tools

Write Tools (CRUD)

⚠️ Write tools modify live data. Use a read-only API key for exploration; only enable write access for known workflows.

💡 Use Cases

1. Generate API Calls

"Get me the last 10 approved work orders from BEDFORD site"

The AI calls get_schema_details(MXWO), understands the fields, and generates:

GET /maximo/api/os/mxwo    ?oslc.where=status="APPR" and siteid="BEDFORD"    &oslc.select=wonum,description,status,reportdate    &oslc.orderBy=-reportdate    &oslc.pageSize=10    &lean=1

2. Generate Python Scripts

"Write a Python script to export all Priority 1 work orders to CSV"

import requestsimport csv
response = requests.get(    "https://your-host/maximo/api/os/mxwo",    params={"oslc.where": "wopriority=1", "lean": 1},    headers={"apikey": "YOUR_KEY"})
with open("priority1_workorders.csv", "w") as f:    writer = csv.DictWriter(f, fieldnames=["wonum", "description"])    writer.writeheader()    writer.writerows(response.json()["member"])

3. Generate SQL Queries

"Write SQL to find overdue work orders"

SELECT wonum, description, status, targcompdateFROM workorderWHERE status NOT IN ('COMP', 'CLOSE', 'CAN')  AND targcompdate < CURRENT_DATE;

4. Build Complete Applications

"Create an HTML dashboard to display assets"

Result: A complete web application with:

• Dark theme with glassmorphism
• Search and filter functionality
• Interactive detail panels
• Pre-loaded data from Maximo

See the Asset Manager Case Study for the full walkthrough.

5. Create & Update Records (CRUD)

"Create a corrective maintenance work order for the BEDFORD site, priority 1, description 'Pump failure inspection'."

The AI calls get_schema_details(MXWO) to confirm field names, then create_record:

POST /maximo/api/os/MXWO?lean=1apikey: YOUR_KEYContent-Type: application/json
{ "description": "Pump failure inspection", "siteid": "BEDFORD", "worktype": "CM", "wopriority": 1 }

"Now approve work order 1025 with memo 'Reviewed and approved'."

POST /maximo/api/os/MXWO/1025?action=changeStatus&lean=1apikey: YOUR_KEYContent-Type: application/json
{ "status": "APPR", "memo": "Reviewed and approved" }

See the full guide: Maximo MCP Server Guide — CRUD Workflows

🧩 VS Code Extensions

This project includes two VS Code extensions for interactive Maximo API development — no AI agent required.

Maximo API Explorer

A full-featured VS Code extension for discovering, testing, and generating code for Maximo REST APIs.

[Maximo API Explorer — Sidebar]

Connected to a live Maximo instance showing Object Structures (MXWO, MXSR, MXASSET, etc.) and API Endpoints.

[Maximo API Explorer — API Tester]

OSLC Query Builder with live JSON response (200 OK, 20 records from MXWO).

Quick Start

cd maximo-api-explorernpm install && npm run compile# Press F5 in VS Code to launch the Extension Development Host

See the full guide: Maximo API Explorer Guide

Maximo Cursor Explorer

A fork of the API Explorer optimized for Cursor's AI features:

cd maximo-cursor-extensionnpm install && npm run compile# Press F5 in VS Code to launch

📁 Project Structure

Maximo-MCP/├── maximo-mcp-server.js       # 🔌 MCP Server implementation├── server.js                  # 🌐 Local proxy server for CORS├── package.json               # 📦 Dependencies & scripts├── README.md                  # This file├── .env.example               # Environment template│├── docs/                      # 📚 Documentation│   ├── Maximo_MCP_Server_Guide.md         # Complete MCP guide│   ├── Maximo_API_Interaction_Guide.md    # API interaction patterns│   ├── Asset_Manager_App_Case_Study.md    # Build walkthrough│   ├── Maximo_API_Explorer_Guide.md       # VS Code extension guide│   ├── Maximo_MCP_Server_Guide_FR.md      # French translation│   └── Maximo_API_Interaction_Guide_FR.md # French translation│├── maximo-api-explorer/       # 🧩 VS Code Extension│   ├── package.json                       # Extension manifest│   ├── src/extension.ts                   # Activation & commands│   ├── src/api/                           # API client & discovery│   ├── src/auth/                          # Authentication manager│   ├── src/views/                         # Sidebar tree & WebView panel│   ├── src/snippets/                      # Multi-language code generator│   ├── src/templates/                     # Carbon app generators│   └── src/export/                        # AI context exporter│├── maximo-cursor-extension/   # 🤖 Cursor-Optimized Extension│   ├── package.json                       # Extension manifest│   ├── src/extension.ts                   # Activation & commands│   ├── src/cursor/                        # .cursorrules, prompts, context│   └── src/...                            # Same structure as api-explorer│├── CodeExample/               # 📦 Standalone Carbon App Example│   └── maximo-workorders-carbon/          # Work Order Browser (reference)│├── demos/                     # 🎨 Demo Applications│   ├── assets.html                        # Asset Manager app│   ├── carbon_workorders.html             # Carbon table demo│   └── index.html                         # API visualization demo│├── images/                    # 📸 Screenshots & Recordings│   ├── assets_demo_recording.webp         # Full demo recording│   ├── assets_loaded.png                  # Dashboard screenshot│   ├── api-explorer-sidebar.png           # Extension sidebar & tree view│   ├── api-explorer-tester.png            # OSLC Query Builder & JSON response│   ├── api-explorer-carbon-app.png        # Generated Work Order Browser app│   ├── api-explorer-snippets.png          # Carbon App Templates (Examples tab)│   └── ...                                # More screenshots│└── config/                    # ⚙️ Configuration Templates    └── mcp_config.json.example            # MCP config template

🔒 Security Best Practices

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol for the MCP specification
• IBM Maximo for the enterprise asset management platform
• Carbon Design System for the UI components