Maximo Enterprise MCP

Maximo Enterprise MCP

一款面向生产环境的集成方案，通过 Model Context Protocol 将 IBM Maximo Asset Management 引入 AI 工作流。

由 Maxis Technology 打造，属于 Alchemize 的一部分——这是一款先进的企业数据管理平台，能在数小时内完成其他平台数天才能完成的工作。想了解更多？请访问 alchemize.io。

此项目现已提供：

• 稳定的 MCP 服务，可供 Claude Desktop、Cursor 和其他 MCP 客户端使用。
• 托管式 HTTP/SSE 模式，支持远程 MCP 访问。
• FastAPI 工具层，适用于 OpenAI、Gemini、Grok 和自定义编排器。

各版本的发布历史请参阅 CHANGELOG.md（第 1–9 轮新增了 64 个工具）。

当前稳定版本包含 21 个类别、95 个公开工具。每个工具都采用严格的 Pydantic 输入模型（extra="forbid"）。

如果客户的 Maximo 中没有填充某个垂直领域的数据（例如没有油气行业的大修、交通运输车队、Spatial 坐标等），每个工具都会返回 data_unavailable=True，并附上易于用户理解的说明，解释缺少哪些内容以及管理员可以采取什么措施。绝不会只返回晦涩难懂的 400/404 错误。

Maximo 版本兼容性

集成套件（64 个新增工具，涵盖 8 轮冒烟测试）已在 **Maximo 7.6.x（含 mxapi 集成扩展）**上完成端到端验证（API 补丁包——已发布 mxapi* 对象结构）。

Maximo 版本	状态	说明
含 mxapi 扩展的 Maximo 7.6.x	✅ 已在线验证（8/8 轮冒烟测试均通过，约 3.5 分钟）	我们用于测试的配置
不含 mxapi 扩展的 Maximo 7.6.x	✅ 应可正常工作	多候选项 mx* → mxapi* 会在回退时正常使用 mx* 路径
MAS 8.x（RHOCP 上的 Manage）	⚠️ 应可正常工作，未经测试	mx* 和 mxapi* 均已发布；MAS SSO 可能需要使用 MCP_AUTH_MODE=jwt
MAS 9.x（RHOCP 上的 Manage）	⚠️ 应可正常工作，未经测试	mxapi* 为首选；身份验证注意事项相同

代码库采用防御性设计，以支持跨版本使用：

• 多候选项 OS 端点（tools/*.py 中的常量，如 JP_OS_CANDIDATES、LABOR_OS_CANDIDATES）会先遍历 mx*，再遍历 mxapi*，并在遇到 404 时回退
• 单条件 WHERE + Python 后置筛选（用于防御已遇到的限制最严格的版本——参见 compound_where_drops_connection）
• +field / -field 排序方向前缀（严格遵循 OSLC v2 规范——适用于所有版本）
• 如果客户部署中未发布 OSLC 对象结构，则优雅地设置 data_unavailable=True 标志，并附上管理员可采取措施的说明 | 类别 | 工具数 | 提供的功能 | |---|---:|---| | 资产 | 9 | 生命周期、历史记录、停机时间 / MTTR / MTBF、搜索、关键性矩阵、保修分组、故障类别层级、仪表读数 | | 工单 | 8 | 列表 / 获取 / KPI、任务拆分、计划与实际差异、成本拆分、日程日历、“分配给我的工单” | | 作业计划 | 3 | 目录列表、包含嵌入式任务 / 人工 / 材料 / 工具的完整计划、根据作业计划估算成本 | | 服务请求 | 2 | 列表 + 获取 — 工单创建前的入口受理 | | 库存 | 8 | 库存查询、低库存列表、补货建议、物料主数据、仓库目录、总估值、关键备件风险 | | 采购 | 6 | 采购订单（列表 + 获取）、采购申请、供应商（列表 + 绩效）、按供应商 / 状态 / 工作类型分析支出 | | 人工 | 5 | 人员 / 班组 / 工种列表、利用率、可用技术人员查找器（优先显示最空闲人员） | | 位置 | 3 | 列表 + 获取 + 层级树 | | 报告 | 6 | 维护 KPI 仪表板、故障 Pareto 分析、问题资产、Excel + PDF 导出、Carbon HTML 表格 | | AI 智能 | 4 | 自然语言转 OSLC、异常检测（>2σ）、根因建议、资产健康评分 | | AI 护城河 （Wave 8） | 6 | 工单摘要、故障自动分类、与资产对话、PM 优化、预测故障时间窗口、运行手册生成 — 每个工具都由 LLM 增强，并带有基于统计 / 规则的回退机制 | | 空间 / GIS （Wave 9） | 2 | 查找指定经纬度附近的资产、优化技术人员路线 — 未填入坐标时优雅回退并提示“Spatial not installed” | | 合规与 EHS | 6 | 校准 / 检查 / 许可证 / 即将到期的认证 / 事件 / 合规仪表板 | | 制药 | 3 | 校准审计追踪（FDA）、洁净室资产、GxP 风险评分 | | 石油与天然气 | 3 | 检修状态、压力容器检查、起重设备登记册 | | 制造业 | 3 | OEE（可用率）、生产线状态、换线（SMED）工单 | | 公用事业 | 3 | 停电影响分析、电网区域资产、SAIDI/SAIFI 代理指标 | | 医疗保健 | 3 | 到期的医疗设备 PM、设备生命周期（NEW/STABLE/AGING/EOL）、JC Environment of Care | | 交通运输 | 3 | 车队就绪率 %、按里程计算的 PM 到期情况、带峰值检测的燃油消耗趋势 | | 架构 / 管理 | 8 | 对象结构发现、架构详情、OSLC 查询验证、代码生成、用户、审计日志、事件订阅 | | 核心 | 1 | health_check — 连通性探测 + 工具数量 |

每个读取工具都会返回结构化封装（success / data / metadata）。如果 Maximo 版本未公开工具所需的数据，工具会显示 data_unavailable: true 标志并附上管理员操作说明，而不是静默失败。写入工具默认均为 # DISABLED。

快速入门提示词

连接到 Claude Desktop / Cursor / Code 后，试试：

Use maximo mcp. Asset 1001 isn't behaving — pull its details, recent work-order
history, and meter readings for the last 90 days.

Use maximo mcp. Run the compliance dashboard for site BEDFORD, then list the top
5 bad-actor assets and any calibrations overdue right now.

Use maximo mcp. I'm new to BEDFORD as planner — show me what job plans we have,
estimate cost for one, and find me an available welder.

Use maximo mcp. QBR slides due Friday. Export work orders to Excel + asset
report to PDF, plus the maintenance KPI dashboard for the cover slide.

Use maximo mcp. Quarterly EHS review — run compliance dashboard, list calibrations
due in 90 days, and certifications expiring in 60.

Use maximo mcp. Pump 1001 has been intermittent. Predict its next failure window,
recommend whether we should tune its PM frequency, and generate a runbook for the
last "grinding noise" complaint based on what we did before.

Use maximo mcp. Summarize WO 6540 for tomorrow's shift handover, then auto-classify
the failure code from this complaint: "intermittent grinding noise during operation".

Use maximo mcp. Chat with asset 1001: when did it last fail, what was the root cause,
and how often does it break?

负责任地使用

此服务会连接到正在运行的 IBM Maximo 实例并公开其数据；明确启用后，还会向大模型开放其变更操作。部署前请：

• 在经过身份验证的网关后运行托管 HTTP/SSE。每个请求的身份来自 MCP_AUTH_MODE=jwt（OIDC）或静态且由网关注入的 X-MCP-* 标头。若前方没有身份验证方案，切勿向不受信任的调用方公开 FastAPI 工具 API。
• 对于任何非 stdio 部署，边缘端的 TLS（或通过 MCP_SSL_* 在进程内配置）都是强制要求。应用自身不会终止 TLS。
• 在审查适用于你所在环境的 RBAC 策略和审计方案前，请在 server.py 中保留所有写入工具的 # DISABLED 状态。
• 为每个部署设置 MAXIMO_ENV=dev|staging|prod，以便通过审计记录和 /healthz 明确容器连接的是哪个 Maximo。
• 在推送到公共注册表前，请阅读 SECURITY.md 和 PRODUCT_GAPS_BEFORE_DEPLOY.md；后者记录了加入 https://github.com/mcp 风格目录所需的具体控制措施。

架构

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

安装

Claude Desktop / Claude Code / Cursor 的本地 MCP

有两种安装方式：uvx（推荐——无需手动安装）或 pip install。

选项 A — uvx（推荐）

先安装一次 uv，然后将 MCP 客户端配置为使用 uvx maximo-enterprise-mcp。uvx 会按需下载、缓存并运行软件包。

选项 B — pip install

pip install maximo-enterprise-mcp

然后在下面的配置中，将：

"command": "uvx",
"args": ["maximo-enterprise-mcp"]

替换为：

"command": "maximo-enterprise-mcp",
"args": []

Claude Desktop

编辑 %APPDATA%\Claude\claude_desktop_config.json（Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）：

{
  "mcpServers": {
    "maximo": {
      "command": "uvx",
      "args": ["maximo-enterprise-mcp"],
      "env": {
        "MAXIMO_URL": "https://your-maximo-host.com/maximo/oslc",
        "MAXIMO_HOST": "https://your-maximo-host.com",
        "AUTH_MODE": "basic",
        "MAXIMO_USERNAME": "your-username",
        "MAXIMO_PASSWORD": "your-password",
        "CURRENT_USER_ROLE": "readonly"
      }
    }
  }
}

重启 Claude Desktop。工具加载后会显示锤子图标。

Claude Code

添加到项目级 .mcp.json 或全局 ~/.claude.json：

{
  "mcpServers": {
    "maximo": {
      "command": "uvx",
      "args": ["maximo-enterprise-mcp"],
      "env": {
        "MAXIMO_URL": "https://your-maximo-host.com/maximo/oslc",
        "MAXIMO_HOST": "https://your-maximo-host.com",
        "AUTH_MODE": "basic",
        "MAXIMO_USERNAME": "your-username",
        "MAXIMO_PASSWORD": "your-password",
        "CURRENT_USER_ROLE": "readonly"
      }
    }
  }
}

在 Claude Code 中运行 /mcp，验证连接。

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（每个项目）：

{
  "mcpServers": {
    "maximo": {
      "command": "uvx",
      "args": ["maximo-enterprise-mcp"],
      "env": {
        "MAXIMO_URL": "https://your-maximo-host.com/maximo/oslc",
        "MAXIMO_HOST": "https://your-maximo-host.com",
        "AUTH_MODE": "basic",
        "MAXIMO_USERNAME": "your-username",
        "MAXIMO_PASSWORD": "your-password",
        "CURRENT_USER_ROLE": "readonly"
      }
    }
  }
}

在 Cursor 中：Settings → MCP → Refresh 以加载。

通过 HTTP/SSE 托管 MCP

托管模式适用于可信网络或受网关保护的部署。现在，除非设置了 MCP_ACCESS_TOKEN，否则该模式会默认拒绝访问。

python server.py --http --host 0.0.0.0 --port 8080

远程 MCP 客户端应连接到：

• MCP SSE 端点：http://host:8080/sse
• 健康检查端点：http://host:8080/healthz

远程 MCP 配置示例：

{
  "mcpServers": {
    "maximo": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer <your MCP_ACCESS_TOKEN>"
      }
    }
  }
}

FastAPI 工具 API

托管 HTTP 模式还会为非 MCP 平台提供工具 API：

• 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

调用示例：

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 平台用法

OpenAI

使用 GET /v1/providers/openai-tools 获取兼容 OpenAI 的工具定义，然后通过 POST /v1/tools/{tool_name} 执行所选工具。

Gemini

使用 GET /v1/providers/gemini-tools，从同一共享工具注册表获取 Gemini 函数声明。

Grok

使用 GET /v1/providers/grok-tools。其负载兼容 OpenAI，因此可以采用相同的编排模式。

可选依赖项

核心安装使用 requirements.txt。

可选扩展定义于 pyproject.toml：

• pip install ".[ai]"：安装 OpenAI、ChromaDB 和 sentence-transformers。
• pip install ".[exports]"：安装 Excel 和 PDF 导出依赖项。
• pip install ".[dev]"：安装本地测试和 lint 工具。

环境变量

完整列表请参阅 .env.example。最重要的变量包括：

变量	必需	说明
MAXIMO_URL	是	完整的 Maximo OSLC 基础 URL
MAXIMO_HOST	是	Maximo 主机根 URL
AUTH_MODE	是	basic、apikey 或 oauth
MAXIMO_USERNAME / MAXIMO_PASSWORD	基本身份验证	Maximo 凭据
MCP_ACCESS_TOKEN	托管 HTTP	托管 MCP/API 模式所需的 bearer token
CURRENT_USER_ROLE	仅本地	本地或可信部署的会话角色
REDIS_URL	否	Redis 缓存连接字符串
VPN_SAFE_MODE	否	启用更安全的默认负载大小
DEFAULT_PAGE_SIZE	否	启用安全模式时的默认页面大小

Docker

构建

docker build -t maximo-enterprise-mcp .

运行

docker run -d ^
  -p 8080:8080 ^
  -e TRANSPORT_MODE=http ^
  -e MCP_ACCESS_TOKEN=change-me ^
  -e MAXIMO_URL=https://your-maximo-host.example.com/maximo/oslc ^
  -e MAXIMO_HOST=https://your-maximo-host.example.com ^
  -e AUTH_MODE=basic ^
  -e MAXIMO_USERNAME=your-maximo-username ^
  -e MAXIMO_PASSWORD=your-maximo-password ^
  maximo-enterprise-mcp

如果要包含 Redis，请使用 docker-compose.yml。

部署指南

服务器本身不会终止 TLS。所有非 stdio 部署都 必须在边缘或进程内通过 MCP_SSL_CERTFILE / MCP_SSL_KEYFILE 终止 TLS。请参阅 SECURITY.md。

AWS

• 推荐的首选目标：ECS Fargate 或 App Runner。
• 在 AWS Secrets Manager 中存储机密。
• **必需：**在前方部署 ALB 或 API Gateway，以提供 TLS 和访问控制。
• 尽可能保持 Maximo 连接为私有连接。

Azure

• 推荐的首选目标：Azure Container Apps 或 App Service。
• 在 Key Vault 中存储机密。
• **必需：**在前方部署 Application Gateway 或 Front Door，以提供 TLS 和访问控制。

环境隔离

运行一个容器镜像、三个部署和三个密钥存储。为每个部署设置 MAXIMO_ENV=dev|staging|prod——该值会写入每条 审计记录和 /healthz，方便运维人员一眼确认 容器连接的是哪个 Maximo。

推荐模式：

部署	MAXIMO_ENV	Maximo 目标	令牌范围
dev	dev	dev Maximo	dev MCP_ACCESS_TOKEN / OIDC 租户
staging	staging	staging Maximo	staging 令牌 / OIDC 租户
prod	prod	prod Maximo	prod 令牌 / OIDC 租户

切勿跨环境复用令牌——泄露的 dev 令牌不得解锁 prod，而误路由的 dev 容器也不得写入 prod 数据。

公共互联网

将原始托管 MCP 暴露到公共互联网，必须满足以下所有条件——无一例外：

• 入站身份验证采用 bearer 或 OIDC（MCP_AUTH_MODE）
• 在边缘层或进程内启用 TLS（应用默认提供明文）
• 明确设置 CORS 允许列表（MCP_ALLOWED_ORIGINS）——切勿使用 *
• 启用速率限制（RATE_LIMIT_PER_MINUTE），并单独配置边缘限流器
• 启用审计日志并持久转发
• 使用私有 Maximo 连接或严格的网络控制

开发

运行单元测试

pytest -m "not integration"

运行集成测试

集成测试会访问 .env 中配置的真实 Maximo 实例。包含两组测试：

• tests/integration_test_tools.py — 针对单个在线 Maximo 按工具逐一进行冒烟测试
• tests/integration/test_smoke_wave[1-4].py — 按 wave 逐一运行冒烟测试，为 wave 1–4/6 中新增的每个公共工具设置准入门槛

# Run every integration test (skipped automatically if MAXIMO_URL is unset)
pytest tests/integration -m integration -v

# Run a single wave's smoke
pytest tests/integration/test_smoke_wave2.py -m integration -v

# Or run a wave standalone for ad-hoc debugging
python tests/integration/test_smoke_wave2.py

列出已注册的 MCP 工具

python server.py --test

安全说明

• 不要提交真实的 .env、.mcp.json 或 .cursor/mcp.json 配置值。
• 使用 *.example 文件中的示例配置，并将密钥保存在仅本地可访问的文件或密钥管理器中。
• 托管模式需要 MCP_ACCESS_TOKEN。
• 基于环境变量的角色模型适用于本地或可信部署，不适用于多租户公共托管。

---

IBM 和 Maximo 是 International Business Machines Corp. 的商标，此处仅用于描述目的。本项目与 IBM 无关联。