IBM Maximo

---

🎯 这是什么？

Maximo MCP Server 是一个 模型上下文协议 服务，可将 AI 助手（如 Antigravity、Cursor 或 VS Code Copilot）直接连接到您的 IBM Maximo 环境。AI 无需手动复制 API 文档，即可：

功能	说明
🔍 发现 API	查找可用的对象结构（MXWO、MXASSET 等）
📋 检查架构	获取准确的字段名称、类型和说明
📊 查询实时数据	执行 OSLC REST 查询并查看真实结果
🎨 生成界面	创建 Carbon Design System 表格和仪表板
✅ 即时验证	在生成最终代码前测试查询
✏️ 创建记录	通过 AI 创建工作订单、资产和服务请求
🔄 更新记录	按 ID 部分更新任意 Maximo 记录
⚡ 运行操作	触发 Maximo 业务工作流（状态变更、审批）

---

📚 文档

核心指南

文档	说明
📖 Maximo MCP Server 指南	完整的设置、配置和工具参考
🔌 Maximo API 交互指南	OSLC 查询语法、代码生成模式和故障排除
🎬 资产管理器案例研究	构建完整应用的分步教程
🧩 Maximo API Explorer 指南	VS Code 扩展：安装、连接、探索和生成应用

法语翻译

文档	说明
📖 Maximo MCP Server 指南	完整指南的法语版本
🔌 Maximo API 交互指南	API 指南的法语版本

Word 文档

所有指南也提供 .docx 格式，存放在 docs/ 文件夹中，便于离线阅读和分享。

---

⚡ 快速开始

先决条件

• Node.js v18 或更高版本
• 具有读取权限的 Maximo API Key
• 支持 MCP 的 AI IDE（Antigravity、Cursor、VS Code + Continue）

安装

安装

方法 1：使用 npx 直接运行（推荐）

npx maximo-mcp-server

方法 2：从源代码克隆

# 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

环境配置

使用您的 Maximo 凭据编辑 .env 文件：

# .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

下载 OpenAPI 架构（推荐）

OpenAPI 架构文件支持离线查询架构，从而加快 AI 响应：

# 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

也可以通过 Swagger UI 下载：https://your-host/maximo/oslc/oas/api.html（点击“Explore”或“Download”）

方法 3：通过浏览器直接下载（手动操作）

如果 curl 失败（例如由于 SSL/网络错误），可以手动下载文件：

1. 在浏览器中打开此 URL： https://[YOUR_MAXIMO_HOST]/maximo/oslc/oas/api （将 [YOUR_MAXIMO_HOST] 替换为实际的服务器地址）

2. 系统可能会提示你登录 Maximo。

3. JSON 加载后，右键点击页面并选择 “Save Page As...”。

4. 将文件保存为项目根文件夹中的 maximo_openapi.json。

注意：此文件约为 12MB，包含 Maximo 实例的所有对象结构定义。

IDE 配置

VS Code 与 GitHub Copilot（推荐）

选项 1：从 MCP Server Gallery 安装

1. 在 VS Code 设置中启用 chat.mcp.gallery.enabled
2. 打开扩展视图（⇧⌘X）
3. 在搜索框中输入 @mcp maximo
4. 点击 Install 添加 Maximo MCP 服务

选项 2：通过 mcp.json 手动添加

1. 打开命令面板（⇧⌘P）→ MCP: Open Workspace Folder Configuration
2. 添加以下配置：

{
  "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 会提示你输入 Maximo 凭据。

💡 提示： 此项目包含 .vscode/mcp.json 文件。如果你克隆此仓库，VS Code 会自动检测 MCP 服务配置。

Google Antigravity（需要手动设置）

⚠️ 注意： Antigravity MCP Store 经过精选，不会自动从注册表发现服务。你必须手动添加此服务。

1. 打开 Antigravity
2. 点击 Agent 面板顶部的“...”下拉菜单
3. 选择“MCP Servers”→“Manage MCP Servers”→“View raw config”
4. 添加到你的 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. 保存并点击 Refresh

Cursor / Claude Desktop

# 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

使用你的 Maximo 凭据编辑：

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

验证连接

在你的 AI IDE 中询问：

“Maximo MCP 服务已连接吗？”

AI 将调用 get_instance_details 并确认连接状态。

---

🎬 在线演示

Asset Manager 应用

我们仅使用自然语言提示词和 MCP 服务，就构建了完整的 Maximo Asset Manager Web 应用。

演示功能

功能	截图
完整仪表板	50 项资产、4 张统计卡片、3 个站点
搜索筛选
站点筛选

🎥 屏幕录制

完整视频演示见：assets_demo_recording.webp

亲自试用

# Start the local proxy server
node server.js

# Open in browser
open http://localhost:3002/demos/assets.html

---

🛠 可用的 MCP 工具

该服务向 AI 提供 9 个工具——6 个读取工具和 3 个写入/CRUD 工具：

读取工具

工具名称	描述
list_object_structures	列出可用的 Maximo 对象结构（API）
get_schema_details	获取对象结构的字段定义
query_maximo	执行 OSLC REST 查询
render_carbon_table	生成 Carbon Design HTML 表格
render_carbon_details	生成记录的详细视图
get_instance_details	检查服务器连接状态

写入工具（CRUD）

⚠️ 写入工具会修改实时数据。 探索时请使用只读 API 密钥；仅在已知工作流需要时启用写入权限。

工具名称	描述
create_record	在任意 Maximo 对象结构中创建新记录
update_record	按 ID 部分更新现有记录的字段
run_action	执行 Maximo 业务操作（状态变更、审批）

💡 使用场景

1. 生成 API 调用

“获取 BEDFORD 站点最近 10 条已批准的工单”

AI 调用 get_schema_details(MXWO)，了解字段后生成：

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. 生成 Python 脚本

“编写一个 Python 脚本，将所有优先级为 1 的工单导出为 CSV”

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. 生成 SQL 查询

“编写 SQL，查找逾期工单”

SELECT wonum, description, status, targcompdate
FROM workorder
WHERE status NOT IN ('COMP', 'CLOSE', 'CAN')
  AND targcompdate < CURRENT_DATE;

4. 构建完整应用

“创建一个用于显示资产的 HTML 仪表板”

**结果：**一个完整的 Web 应用，包含：

• 暗色主题和玻璃拟态效果
• 搜索和筛选功能
• 交互式详情面板
• 从 Maximo 预加载的数据

完整演示请参阅 Asset Manager 案例研究。

5. 创建和更新记录（CRUD）

“为 BEDFORD 站点创建一张纠正性维护工单，优先级为 1，描述为 ‘Pump failure inspection’。”

AI 调用 get_schema_details(MXWO) 确认字段名称，然后调用 create_record：

POST /maximo/api/os/MXWO?lean=1
apikey: YOUR_KEY
Content-Type: application/json

{ "description": "Pump failure inspection", "siteid": "BEDFORD", "worktype": "CM", "wopriority": 1 }

“现在批准工单 1025，备注为 ‘Reviewed and approved’。”

POST /maximo/api/os/MXWO/1025?action=changeStatus&lean=1
apikey: YOUR_KEY
Content-Type: application/json

{ "status": "APPR", "memo": "Reviewed and approved" }

完整指南请参阅：Maximo MCP 服务指南 — CRUD 工作流

---

🧩 VS Code 扩展

此项目包含两个用于交互式 Maximo API 开发的 VS Code 扩展——无需 AI Agent。

Maximo API Explorer

一款功能齐全的 VS Code 扩展，用于发现、测试 Maximo REST API 并为其生成代码。

已连接到实时 Maximo 实例，显示对象结构（MXWO、MXSR、MXASSET 等）和 API 端点。

功能	说明
侧边栏树视图	浏览所有对象结构（MXWO、MXASSET、MXSR 等）及其属性、类型和关系
交互式 API 测试器	通过 WebView 面板以可视化方式构建 OSLC 查询、发送原始请求并检查架构
代码片段生成器	生成可直接使用的 API 调用，支持 cURL、Python、JavaScript、TypeScript 和 Java
Carbon 应用生成器	一键搭建完整的工单浏览器和资产管理器 Web 应用
导出供 AI Agent 使用	将架构和文档导出到 .maximo/，供 Copilot、Cursor 或任何 AI 助手使用

OSLC 查询构建器及实时 JSON 响应（200 OK，来自 MXWO 的 20 条记录）。

快速入门

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

完整指南请参阅：Maximo API Explorer 指南

Maximo Cursor Explorer

这是 API Explorer 的一个分支，针对 Cursor 的 AI 功能进行了优化：

功能	说明
.cursorrules 生成器	自动生成规则，让 Cursor AI 深入了解 Maximo API
AI 上下文导出	将架构导出到 .cursor/context/，以便通过 @file 引用
提示词模板	为 OSLC 查询、CRUD 服务、仪表板等预先构建的提示词
所有标准功能	包含 API Explorer 的全部功能，另有专用的 Cursor AI 选项卡

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

---

📁 项目结构

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

---

🔒 安全最佳实践

实践	说明
🔐 本地执行	MCP 服务在你的计算机上运行；API 密钥不会离开你的环境
📖 开发使用只读密钥	使用权限受限的 API 密钥进行探索和开发
✏️ 单独使用写入密钥	仅为用于已知 CRUD 工作流的 API 密钥启用写入权限
🔒 环境变量	切勿在配置文件中硬编码凭据
🌐 仅使用 HTTPS	始终使用加密连接访问 Maximo
🧪 先在非生产环境中测试	投入生产环境前，务必先在开发/测试实例上验证 CRUD 操作

---

🤝 贡献

欢迎贡献！提交 PR 前，请先阅读我们的贡献指南。

1. Fork 此存储库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

---

📄 许可证

本项目采用 Apache License 2.0 许可协议，详情请参阅 LICENSE 文件。

---

🙏 致谢

• Model Context Protocol：提供 MCP 规范
• IBM Maximo：提供企业资产管理平台
• Carbon Design System：提供 UI 组件