{
  "markdown": "# Maximo Enterprise MCP\n\n<!-- mcp-name: io.github.MaxisTechnology-Dev/maximo-mcp -->\n\nA production-focused integration that brings IBM Maximo Asset Management into AI workflows through the Model Context Protocol.\n\nBuilt by [Maxis Technology](https://maxistechnology.com) as part of **Alchemize** — a state-of-the-art enterprise data management platform capable of doing in hours what others do in days. Want to know more? Head over to [alchemize.io](https://alchemize.io/).\n\nThis project now exposes:\n\n- A stable MCP server for Claude Desktop, Cursor, and other MCP clients.\n- A hosted HTTP/SSE mode for remote MCP access.\n- A FastAPI tool layer for OpenAI, Gemini, Grok, and custom orchestrators.\n\nSee [CHANGELOG.md](CHANGELOG.md) for the per-version release history (64 net-new tools across waves 1–9).\n\nThe current stable surface is **95 public tools** across 21 categories. Every tool ships with a strict Pydantic input model (`extra=\"forbid\"`).\n\n> When a customer's Maximo doesn't have a particular vertical's data populated (no oil-and-gas turnarounds, no transportation fleet, no Spatial coordinates, etc.), every tool returns `data_unavailable=True` with a **user-friendly note explaining what's missing and what an admin can do**. Never a cryptic 400/404.\n\n### Maximo version compatibility\n\nThe integration suite (64 net-new tools across 8 wave smoke tests) is verified end-to-end against **Maximo 7.6.x with the mxapi integration extensions** (the API patch pack — `mxapi*` object structures published).\n\n| Maximo build | Status | Notes |\n|---|---|---|\n| Maximo 7.6.x with mxapi extensions | ✅ **Verified live** (8/8 wave smokes pass in ~3.5 minutes) | The configuration we test against |\n| Maximo 7.6.x without mxapi extensions | ✅ Should work | Multi-candidate `mx*` → `mxapi*` falls back to `mx*` paths cleanly |\n| MAS 8.x (Manage on RHOCP) | ⚠️ Should work, not tested | Both `mx*` and `mxapi*` published; auth flow may need `MCP_AUTH_MODE=jwt` for MAS SSO |\n| MAS 9.x (Manage on RHOCP) | ⚠️ Should work, not tested | `mxapi*` is primary; same auth caveat |\n\nThe codebase is defensively designed for cross-version use:\n- Multi-candidate OS endpoints (`tools/*.py` constants like `JP_OS_CANDIDATES`, `LABOR_OS_CANDIDATES`) iterate `mx*` first then `mxapi*` and fall through 404s\n- Single-condition WHERE + Python post-filter (defensive against the most restrictive build encountered — see [`compound_where_drops_connection`](memory))\n- `+field` / `-field` orderBy direction prefix (strict OSLC v2 spec — works on every build)\n- Graceful `data_unavailable=True` flag with admin-action note when an OSLC object structure isn't published on the customer's deployment\n\n| Category | Tools | What it gives you |\n|---|---:|---|\n| Assets | 9 | Lifecycle, history, downtime / MTTR / MTBF, search, criticality matrix, warranty buckets, failure-class hierarchy, meter readings |\n| Work orders | 8 | List / get / KPIs, task breakdown, planned-vs-actual variance, cost breakdown, schedule calendar, \"my assigned WOs\" |\n| Job plans | 3 | Catalog list, full plan with embedded tasks/labor/materials/tools, cost estimate from job plan |\n| Service requests | 2 | List + get — front-door intake before WOs |\n| Inventory | 8 | Stock check, low-stock list, reorder recs, item master, storeroom catalog, total valuation, critical-spares risk |\n| Purchasing | 6 | POs (list + get), purchase requisitions, vendors (list + performance), spend analysis by vendor / status / worktype |\n| Labor | 5 | List labor / crews / crafts, utilization, **available-technician finder** (least-busy first) |\n| Locations | 3 | List + get + hierarchy tree |\n| Reporting | 6 | Maintenance KPI dashboard, failure Pareto, bad-actor assets, Excel + PDF export, Carbon HTML table |\n| AI intelligence | 4 | NL-to-OSLC, anomaly detection (>2σ), root-cause suggestion, asset health score |\n| **AI moat** *(Wave 8)* | 6 | WO summary, auto-classify failure, **chat with asset**, PM optimization, predict failure window, **runbook generation** — every tool LLM-enhanced with statistical/rule-based fallback |\n| **Spatial / GIS** *(Wave 9)* | 2 | Find assets near a lat/lon, optimised technician routing — graceful \"Spatial not installed\" fallback when coordinates aren't populated |\n| Compliance & EHS | 6 | Calibrations / inspections / permits / certifications-expiring / incidents / **compliance dashboard** |\n| Pharma | 3 | Calibration audit trail (FDA), cleanroom assets, GxP risk score |\n| Oil & Gas | 3 | Turnaround status, pressure-vessel inspections, lifting register |\n| Manufacturing | 3 | OEE (Availability), production-line status, changeover (SMED) WOs |\n| Utilities | 3 | Outage impact analysis, grid-zone assets, SAIDI/SAIFI proxies |\n| Healthcare | 3 | Medical-device PM due, device lifecycle (NEW/STABLE/AGING/EOL), JC Environment of Care |\n| Transportation | 3 | Fleet readiness %, mileage-based PM due, fuel consumption trend with spike detection |\n| Schema / Admin | 8 | Object-structure discovery, schema details, OSLC query validation, code generation, users, audit log, event subscriptions |\n| Core | 1 | `health_check` — connectivity probe + tool count |\n\nEvery read tool returns a structured envelope (`success / data / metadata`). Tools that need data their Maximo build doesn't expose surface a `data_unavailable: true` flag with an admin-action note rather than failing silently. Write tools ship `# DISABLED` by default.\n\n### Quick-start prompts\n\nOnce connected to Claude Desktop / Cursor / Code, try:\n\n```\nUse maximo mcp. Asset 1001 isn't behaving — pull its details, recent work-order\nhistory, and meter readings for the last 90 days.\n\nUse maximo mcp. Run the compliance dashboard for site BEDFORD, then list the top\n5 bad-actor assets and any calibrations overdue right now.\n\nUse maximo mcp. I'm new to BEDFORD as planner — show me what job plans we have,\nestimate cost for one, and find me an available welder.\n\nUse maximo mcp. QBR slides due Friday. Export work orders to Excel + asset\nreport to PDF, plus the maintenance KPI dashboard for the cover slide.\n\nUse maximo mcp. Quarterly EHS review — run compliance dashboard, list calibrations\ndue in 90 days, and certifications expiring in 60.\n\nUse maximo mcp. Pump 1001 has been intermittent. Predict its next failure window,\nrecommend whether we should tune its PM frequency, and generate a runbook for the\nlast \"grinding noise\" complaint based on what we did before.\n\nUse maximo mcp. Summarize WO 6540 for tomorrow's shift handover, then auto-classify\nthe failure code from this complaint: \"intermittent grinding noise during operation\".\n\nUse maximo mcp. Chat with asset 1001: when did it last fail, what was the root cause,\nand how often does it break?\n```\n\n## Responsible Use\n\nThis server speaks to a live IBM Maximo instance and exposes its data — and,\nwhen explicitly enabled, its mutating operations — to a language model. Before\ndeploying:\n\n- Run hosted HTTP/SSE behind an authenticated gateway. Per-request identity\n  comes from `MCP_AUTH_MODE=jwt` (OIDC) or static + gateway-injected\n  `X-MCP-*` headers. Never expose the FastAPI tool API to untrusted callers\n  without an identity solution in front.\n- TLS at the edge (or in-process via `MCP_SSL_*`) is mandatory for any\n  non-stdio deployment. The app does not terminate TLS itself.\n- Keep all write tools `# DISABLED` in [server.py](server.py) until you have\n  reviewed the RBAC policy and audit posture for your environment.\n- Stamp `MAXIMO_ENV=dev|staging|prod` per deployment so audit records and\n  `/healthz` make it obvious which Maximo a container is talking to.\n- Read [SECURITY.md](SECURITY.md) and\n  [PRODUCT_GAPS_BEFORE_DEPLOY.md](PRODUCT_GAPS_BEFORE_DEPLOY.md) before\n  pushing to a public registry; the latter documents the exact controls\n  required for `https://github.com/mcp`-style listings.\n\n## Architecture\n\n```text\nLocal MCP clients        -> stdio MCP server -> Maximo OSLC\nRemote MCP clients       -> HTTP gateway -> hosted MCP SSE -> Maximo OSLC\nOpenAI / Gemini / Grok   -> FastAPI tool API -> shared executor -> Maximo OSLC\n```\n\n## Installation\n\n### Local MCP for Claude Desktop / Claude Code / Cursor\n\nYou have two ways to install: `uvx` (recommended — no manual install) or `pip install`.\n\n#### Option A — `uvx` (recommended)\n\nInstall [`uv`](https://docs.astral.sh/uv/getting-started/installation/) once, then point your MCP client at `uvx maximo-enterprise-mcp`. `uvx` downloads, caches, and runs the package on demand.\n\n#### Option B — `pip install`\n\n```bash\npip install maximo-enterprise-mcp\n```\n\nThen in the configs below, replace:\n\n```json\n\"command\": \"uvx\",\n\"args\": [\"maximo-enterprise-mcp\"]\n```\n\nwith:\n\n```json\n\"command\": \"maximo-enterprise-mcp\",\n\"args\": []\n```\n\n#### Claude Desktop\n\nEdit `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"maximo\": {\n      \"command\": \"uvx\",\n      \"args\": [\"maximo-enterprise-mcp\"],\n      \"env\": {\n        \"MAXIMO_URL\": \"https://your-maximo-host.com/maximo/oslc\",\n        \"MAXIMO_HOST\": \"https://your-maximo-host.com\",\n        \"AUTH_MODE\": \"basic\",\n        \"MAXIMO_USERNAME\": \"your-username\",\n        \"MAXIMO_PASSWORD\": \"your-password\",\n        \"CURRENT_USER_ROLE\": \"readonly\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The hammer icon appears once tools load.\n\n#### Claude Code\n\nAdd to project-level `.mcp.json` or global `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"maximo\": {\n      \"command\": \"uvx\",\n      \"args\": [\"maximo-enterprise-mcp\"],\n      \"env\": {\n        \"MAXIMO_URL\": \"https://your-maximo-host.com/maximo/oslc\",\n        \"MAXIMO_HOST\": \"https://your-maximo-host.com\",\n        \"AUTH_MODE\": \"basic\",\n        \"MAXIMO_USERNAME\": \"your-username\",\n        \"MAXIMO_PASSWORD\": \"your-password\",\n        \"CURRENT_USER_ROLE\": \"readonly\"\n      }\n    }\n  }\n}\n```\n\nRun `/mcp` in Claude Code to verify the connection.\n\n#### Cursor\n\nAdd to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):\n\n```json\n{\n  \"mcpServers\": {\n    \"maximo\": {\n      \"command\": \"uvx\",\n      \"args\": [\"maximo-enterprise-mcp\"],\n      \"env\": {\n        \"MAXIMO_URL\": \"https://your-maximo-host.com/maximo/oslc\",\n        \"MAXIMO_HOST\": \"https://your-maximo-host.com\",\n        \"AUTH_MODE\": \"basic\",\n        \"MAXIMO_USERNAME\": \"your-username\",\n        \"MAXIMO_PASSWORD\": \"your-password\",\n        \"CURRENT_USER_ROLE\": \"readonly\"\n      }\n    }\n  }\n}\n```\n\nIn Cursor: Settings → MCP → Refresh to load.\n\n### Hosted MCP over HTTP/SSE\n\nHosted mode is intended for trusted network or gateway-protected deployments. It now fails closed unless `MCP_ACCESS_TOKEN` is set.\n\n```bash\npython server.py --http --host 0.0.0.0 --port 8080\n```\n\nRemote MCP clients should connect to:\n\n- MCP SSE endpoint: `http://host:8080/sse`\n- Health endpoint: `http://host:8080/healthz`\n\nExample remote MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"maximo\": {\n      \"type\": \"sse\",\n      \"url\": \"http://localhost:8080/sse\",\n      \"headers\": {\n        \"Authorization\": \"Bearer <your MCP_ACCESS_TOKEN>\"\n      }\n    }\n  }\n}\n```\n\n### FastAPI Tool API\n\nHosted HTTP mode also exposes a tool API for non-MCP platforms:\n\n- `GET /healthz`\n- `GET /v1/tools`\n- `POST /v1/tools/{tool_name}`\n- `GET /v1/providers/openai-tools`\n- `GET /v1/providers/gemini-tools`\n- `GET /v1/providers/grok-tools`\n\nExample invocation:\n\n```bash\ncurl -X POST http://localhost:8080/v1/tools/list_assets \\\n  -H \"Authorization: Bearer $MCP_ACCESS_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\\\"site_id\\\":\\\"BEDFORD\\\",\\\"page_size\\\":10}\"\n```\n\n## AI Platform Usage\n\n### OpenAI\n\nUse `GET /v1/providers/openai-tools` to retrieve OpenAI-compatible tool definitions, then execute the selected tool via `POST /v1/tools/{tool_name}`.\n\n### Gemini\n\nUse `GET /v1/providers/gemini-tools` to retrieve Gemini function declarations from the same shared tool registry.\n\n### Grok\n\nUse `GET /v1/providers/grok-tools`. The payload is OpenAI-compatible so the same orchestration pattern works.\n\n## Optional Dependencies\n\nCore installation uses `requirements.txt`.\n\nOptional extras are defined in [`pyproject.toml`](pyproject.toml):\n\n- `pip install \".[ai]\"` for OpenAI, ChromaDB, and sentence-transformers.\n- `pip install \".[exports]\"` for Excel and PDF export dependencies.\n- `pip install \".[dev]\"` for local test and lint tooling.\n\n## Environment Variables\n\nSee [`.env.example`](.env.example) for the complete set. The most important variables are:\n\n| Variable | Required | Description |\n|---|---|---|\n| `MAXIMO_URL` | Yes | Full Maximo OSLC base URL |\n| `MAXIMO_HOST` | Yes | Maximo host root URL |\n| `AUTH_MODE` | Yes | `basic`, `apikey`, or `oauth` |\n| `MAXIMO_USERNAME` / `MAXIMO_PASSWORD` | Basic auth | Maximo credentials |\n| `MCP_ACCESS_TOKEN` | Hosted HTTP | Required bearer token for hosted MCP/API mode |\n| `CURRENT_USER_ROLE` | Local only | Session role for local or trusted deployments |\n| `REDIS_URL` | No | Redis cache connection string |\n| `VPN_SAFE_MODE` | No | Enables safer default payload sizes |\n| `DEFAULT_PAGE_SIZE` | No | Default page size when safe mode is enabled |\n\n## Docker\n\n### Build\n\n```bash\ndocker build -t maximo-enterprise-mcp .\n```\n\n### Run\n\n```bash\ndocker run -d ^\n  -p 8080:8080 ^\n  -e TRANSPORT_MODE=http ^\n  -e MCP_ACCESS_TOKEN=change-me ^\n  -e MAXIMO_URL=https://your-maximo-host.example.com/maximo/oslc ^\n  -e MAXIMO_HOST=https://your-maximo-host.example.com ^\n  -e AUTH_MODE=basic ^\n  -e MAXIMO_USERNAME=your-maximo-username ^\n  -e MAXIMO_PASSWORD=your-maximo-password ^\n  maximo-enterprise-mcp\n```\n\nUse [`docker-compose.yml`](docker-compose.yml) if you want Redis included.\n\n## Deployment Guidance\n\nThe server does NOT terminate TLS itself. Every non-stdio deployment\nMUST terminate TLS either at the edge or in-process via\n`MCP_SSL_CERTFILE` / `MCP_SSL_KEYFILE`. See [SECURITY.md](SECURITY.md).\n\n### AWS\n\n- Recommended first target: ECS Fargate or App Runner.\n- Store secrets in AWS Secrets Manager.\n- **Required:** put ALB or API Gateway in front for TLS and access control.\n- Keep Maximo connectivity private when possible.\n\n### Azure\n\n- Recommended first target: Azure Container Apps or App Service.\n- Store secrets in Key Vault.\n- **Required:** put Application Gateway or Front Door in front for TLS and access control.\n\n### Environment Separation\n\nRun one container image, three deployments, three secret stores. Stamp\n`MAXIMO_ENV=dev|staging|prod` per deployment — the value lands in every\naudit record and on `/healthz`, so an operator can confirm at a glance\nwhich Maximo a given container is pointed at.\n\nRecommended pattern:\n\n| Deployment | `MAXIMO_ENV` | Maximo target | Token scope |\n|---|---|---|---|\n| dev      | `dev`     | dev Maximo     | dev `MCP_ACCESS_TOKEN` / OIDC tenant |\n| staging  | `staging` | staging Maximo | staging token / OIDC tenant |\n| prod     | `prod`    | prod Maximo    | prod token / OIDC tenant |\n\nNever reuse a token across environments — a leaked dev token must not\nunlock prod, and a misrouted dev container must not write to prod data.\n\n### Public Internet\n\nExposing the raw hosted MCP to the public internet requires ALL of the\nfollowing — no exceptions:\n\n- bearer or OIDC inbound authentication (`MCP_AUTH_MODE`)\n- TLS at the edge or in-process (the app serves plaintext by default)\n- explicit CORS allowlist (`MCP_ALLOWED_ORIGINS`) — do NOT use `*`\n- rate limiting (`RATE_LIMIT_PER_MINUTE`) and a separate edge limiter\n- audit logging with durable forwarding\n- private Maximo connectivity or strict network controls\n\n## Development\n\n### Run unit tests\n\n```bash\npytest -m \"not integration\"\n```\n\n### Run integration tests\n\nIntegration tests hit a real Maximo instance configured in `.env`. Two suites:\n\n- `tests/integration_test_tools.py` — tool-by-tool smoke against a single live Maximo\n- `tests/integration/test_smoke_wave[1-4].py` — per-wave smoke runs that gate every public tool added in waves 1–4/6\n\n```bash\n# Run every integration test (skipped automatically if MAXIMO_URL is unset)\npytest tests/integration -m integration -v\n\n# Run a single wave's smoke\npytest tests/integration/test_smoke_wave2.py -m integration -v\n\n# Or run a wave standalone for ad-hoc debugging\npython tests/integration/test_smoke_wave2.py\n```\n\n### List registered MCP tools\n\n```bash\npython server.py --test\n```\n\n## Security Notes\n\n- Do not commit real `.env`, `.mcp.json`, or `.cursor/mcp.json` values.\n- Use example configs from the `*.example` files and keep secrets in local-only files or a secret manager.\n- Hosted mode requires `MCP_ACCESS_TOKEN`.\n- The env-based role model is suitable for local or trusted deployments, not multi-tenant public hosting.\n\n---\n\n*IBM and Maximo are trademarks of International Business Machines Corp., used here for descriptive purposes only. This project is not affiliated with IBM.*",
  "bytes": 16787,
  "sha": "f59113e38c5acb17930cbb1de692b41637328df3ddf558d52585bf9c2dccd7de",
  "repo_slug": "maxistechnology-dev/maximo-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_maxistechnology_dev_maximo_mcp_8e9d1721/readme"
}