IBM Maximo
Connect AI assistants to IBM Maximo for API discovery, OSLC querying, and Carbon UI generation.
Open source Open in the app JSON README (API)
About
Connect AI assistants to IBM Maximo for API discovery, OSLC querying, and Carbon UI generation.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- markusvankempen
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.1.0
- Stars
- 8
- Forks
- 2
- Last push
- 2026-02-08T14:33:29Z
- Repository state
- ativo
- Language
- JavaScript
- License
- Apache-2.0
- Added
- 2026-08-29 04:00:29
- Updated
- 2026-08-29 04:00:29
- Origin id
io.github.markusvankempen/maximo-mcp-server
README
<div align="center">
# 🏭 Maximo MCP Server
### AI-Powered Development for IBM Maximo
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
[](https://www.ibm.com/products/maximo)
[](LICENSE)
[](package.json)
*Transform your Maximo development workflow with AI-driven schema discovery, live data querying, and intelligent code generation.*
**Author:** Markus van Kempen
**Email:** mvankempen@ca.ibm.com | markus.van.kempen@gmail.com
**Date:** 5 February 2026
[Getting Started](#-quick-start) • [Documentation](#-documentation) • [Live Demo](#-live-demo) • [Use Cases](#-use-cases)
</div>
---
## 🎯 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 |
---
## 📚 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 |
### 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
#### 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.
<div align="center">
*50 assets loaded with real-time filtering and search*
</div>
#### Demo Features
| Feature | Screenshot |
|---------|------------|
| **Full Dashboard** | 50 assets, 4 stat cards, 3 sites |
| **Search Filter** |  |
| **Site Filter** |  |
#### 🎥 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 6 tools to the AI:
| 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 |
---
## 💡 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.
---
## 📁 Project Structure
```
Maximo-MCP/
├── maximo-mcp-server.js # 🔌 MCP Server implementation
├── server.js # 🌐 Local proxy server for CORS
├── package.json # 📦 Dependencies
├── README.md # This file
├── .env.example # Environment template
├── .gitignore # Git ignore rules
│
├── 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_MCP_Server_Guide_FR.md # French translation
│ └── Maximo_API_Interaction_Guide_FR.md # French translation
│
├── 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
│ ├── pump_search_results.png # Search demo
│ └── laredo_filtered.png # Filter demo
│
└── 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** | Use limited-permission API keys for development |
| 🔒 **Environment Variables** | Never hardcode credentials in config files |
| 🌐 **HTTPS Only** | Always use encrypted connections to Maximo |
---
## 🤝 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 MIT License - 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