# 🏭 Maximo MCP Server ### AI-Powered Development for IBM Maximo [![Node.js](https://img.shields.io/badge/Node.js-18+-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org/) [![MCP](https://img.shields.io/badge/MCP-Protocol-5A29E4?style=for-the-badge)](https://modelcontextprotocol.io/) [![Maximo](https://img.shields.io/badge/IBM-Maximo-052FAD?style=for-the-badge&logo=ibm&logoColor=white)](https://www.ibm.com/products/maximo) [![License](https://img.shields.io/badge/License-Apache%202.0-green?style=for-the-badge)](LICENSE) [![Version](https://img.shields.io/badge/Version-v1.2.1-blue?style=for-the-badge)](package.json) *Transform your Maximo development workflow with AI-driven schema discovery, live data querying, intelligent code generation, and full write-back capabilities.* **Author:** Markus van Kempen **Email:** mvankempen@ca.ibm.com | markus.van.kempen@gmail.com **Date:** 16 September 2026 [Getting Started](#-quick-start) β€’ [Documentation](#-documentation) β€’ [Live Demo](#-live-demo) β€’ [Use Cases](#-use-cases)
--- ## 🎯 What is This? The **Maximo MCP Server** is a [Model Context Protocol](https://modelcontextprotocol.io/) 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: | Capability | Description | |------------|-------------| | πŸ” **Discover APIs** | Find available Object Structures (MXWO, MXASSET, etc.) | | πŸ“‹ **Inspect Schemas** | Get exact field names, types, and descriptions | | πŸ“Š **Query Live Data** | Execute OSLC REST queries and see real results | | 🎨 **Generate UI** | Create Carbon Design System tables and dashboards | | βœ… **Validate Instantly** | Test queries before generating final code | | ✏️ **Create Records** | Create Work Orders, Assets, Service Requests via AI | | πŸ”„ **Update Records** | Partially update any Maximo record by ID | | ⚑ **Run Actions** | Trigger Maximo business workflows (status changes, approvals) | --- ## πŸ“š Documentation ### Core Guides | Document | Description | |----------|-------------| | πŸ“– [**Maximo MCP Server Guide**](docs/Maximo_MCP_Server_Guide.md) | Complete setup, configuration, and tool reference | | πŸ”Œ [**Maximo API Interaction Guide**](docs/Maximo_API_Interaction_Guide.md) | OSLC query syntax, code generation patterns, troubleshooting | | 🎬 [**Asset Manager Case Study**](docs/Asset_Manager_App_Case_Study.md) | Step-by-step walkthrough of building a complete app | | 🧩 [**Maximo API Explorer Guide**](docs/Maximo_API_Explorer_Guide.md) | VS Code extension: install, connect, explore, generate apps | ### French Translations | Document | Description | |----------|-------------| | πŸ“– [Guide du Serveur MCP Maximo](docs/Maximo_MCP_Server_Guide_FR.md) | Version franΓ§aise du guide complet | | πŸ”Œ [Guide d'Interaction API Maximo](docs/Maximo_API_Interaction_Guide_FR.md) | Version franΓ§aise du guide API | ### 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)** ```bash npx maximo-mcp-server ``` **Method 2: Clone from Source** ```bash # Clone the repository git clone https://github.com/markusvankempen/maximo-mcp-ai-integration-options.git cd maximo-mcp-ai-integration-options # Install dependencies npm install # Set up environment variables cp .env.example .env # Edit .env with your Maximo credentials ``` ### Environment Configuration Edit the `.env` file with your Maximo credentials: ```bash # .env (never commit this file!) MAXIMO_URL=https://your-maximo-host.com/maximo/api MAXIMO_HOST=https://your-maximo-host.com MAXIMO_API_KEY=your-api-key-here MAXIMO_OPENAPI_PATH=./maximo_openapi.json PORT=3002 ``` ### Download the OpenAPI Schema (Recommended) The OpenAPI schema file enables offline schema lookups for faster AI responses: ```bash # Download from your Maximo instance curl -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: ```json { "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`: ```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 ```bash # Copy the template cp 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: ```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" } } } } ``` ### 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.
![Asset Manager Dashboard](images/assets_loaded.png) *50 assets loaded with real-time filtering and search*
#### Demo Features | Feature | Screenshot | |---------|------------| | **Full Dashboard** | 50 assets, 4 stat cards, 3 sites | | **Search Filter** | ![Pump Search](images/pump_search_results.png) | | **Site Filter** | ![LAREDO Filter](images/laredo_filtered.png) | #### πŸŽ₯ Screen Recording A complete video demonstration is available: [`assets_demo_recording.webp`](images/assets_demo_recording.webp) #### Try It Yourself ```bash # Start the local proxy server node server.js # Open in browser open 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](images/mcp_tools_ui.png) ### Read Tools | Tool Name | Description | | :--- | :--- | | `list_object_structures` | List available Maximo Object Structures (APIs) | | `get_schema_details` | Get field definitions for an Object Structure | | `query_maximo` | Execute OSLC REST queries | | `render_carbon_table` | Generate Carbon Design HTML tables | | `render_carbon_details` | Generate detail view for a record | | `get_instance_details` | Check server connectivity | ### Write Tools (CRUD) > ⚠️ **Write tools modify live data.** Use a read-only API key for exploration; only enable write access for known workflows. | Tool Name | Description | | :--- | :--- | | `create_record` | Create a new record in any Maximo Object Structure | | `update_record` | Partially update fields on an existing record by ID | | `run_action` | Execute Maximo business actions (status changes, approvals) | --- ## πŸ’‘ 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: ```http 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" ```python import requests import 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" ```sql SELECT wonum, description, status, targcompdate FROM workorder WHERE 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](docs/Asset_Manager_App_Case_Study.md) 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`: ```http POST /maximo/api/os/MXWO?lean=1 apikey: YOUR_KEY Content-Type: application/json { "description": "Pump failure inspection", "siteid": "BEDFORD", "worktype": "CM", "wopriority": 1 } ``` > "Now approve work order 1025 with memo 'Reviewed and approved'." ```http POST /maximo/api/os/MXWO/1025?action=changeStatus&lean=1 apikey: YOUR_KEY Content-Type: application/json { "status": "APPR", "memo": "Reviewed and approved" } ``` See the full guide: [**Maximo MCP Server Guide β€” CRUD Workflows**](docs/Maximo_MCP_Server_Guide.md#65-crud-workflows-write-back-to-maximo) --- ## 🧩 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](images/api-explorer-sidebar.png) *Connected to a live Maximo instance showing Object Structures (MXWO, MXSR, MXASSET, etc.) and API Endpoints.* | Feature | Description | |---------|-------------| | **Sidebar Tree View** | Browse all Object Structures (MXWO, MXASSET, MXSR, etc.) with attributes, types, and relationships | | **Interactive API Tester** | Build OSLC queries visually, send raw requests, inspect schemas β€” all in a WebView panel | | **Code Snippet Generator** | Generate ready-to-use API calls in cURL, Python, JavaScript, TypeScript, and Java | | **Carbon App Generator** | Scaffold complete Work Order Browser and Asset Manager web apps with one click | | **Export for AI Agents** | Export schemas and docs to `.maximo/` for use with Copilot, Cursor, or any AI assistant | ![Maximo API Explorer β€” API Tester](images/api-explorer-tester.png) *OSLC Query Builder with live JSON response (200 OK, 20 records from MXWO).* #### Quick Start ```bash cd maximo-api-explorer npm install && npm run compile # Press F5 in VS Code to launch the Extension Development Host ``` See the full guide: [**Maximo API Explorer Guide**](docs/Maximo_API_Explorer_Guide.md) ### Maximo Cursor Explorer A fork of the API Explorer optimized for [Cursor](https://cursor.com)'s AI features: | Feature | Description | |---------|-------------| | **.cursorrules Generator** | Auto-generate rules giving Cursor AI deep Maximo API knowledge | | **AI Context Export** | Export schemas to `.cursor/context/` for use with `@file` references | | **Prompt Templates** | Pre-built prompts for OSLC queries, CRUD services, dashboards, and more | | **All Standard Features** | Everything from the API Explorer, plus a dedicated Cursor AI tab | ```bash cd maximo-cursor-extension npm 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 | Practice | Description | |----------|-------------| | πŸ” **Local Execution** | MCP server runs on your machine; API keys never leave your environment | | πŸ“– **Read-Only Keys for Dev** | Use limited-permission API keys for exploration and development | | ✏️ **Separate Write Keys** | Only enable write permissions on API keys used for known CRUD workflows | | πŸ”’ **Environment Variables** | Never hardcode credentials in config files | | 🌐 **HTTPS Only** | Always use encrypted connections to Maximo | | πŸ§ͺ **Test Non-Production First** | Always validate CRUD operations on a dev/test instance before production | --- ## 🀝 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](LICENSE) file for details. --- ## πŸ™ Acknowledgments - [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification - [IBM Maximo](https://www.ibm.com/products/maximo) for the enterprise asset management platform - [Carbon Design System](https://carbondesignsystem.com/) for the UI components