IBM Maximo MAS 9.x MCP Server

The most comprehensive Model Context Protocol server for IBM Maximo Application Suite

143 tools across 16 modules — Work Orders, Assets, Inventory, Service Requests, Purchase Orders, Preventive Maintenance, Job Plans, Persons & Labor, Locations, Classifications, Attachments, Analytics, Scheduling, Query & Search, Bulk Operations, and Developer Tools.

Quick Start · Documentation · Examples · Contributing

Overview

This MCP server enables AI assistants (like Claude) and developers to interact with IBM Maximo Application Suite 9.x through 143 purpose-built tools spanning every major Maximo functional area. Designed for enterprise development, testing, and automation workflows.

Why This Server?

Complete Coverage — Every major Maximo module is represented, from work order lifecycle management to preventive maintenance scheduling
AI-Native — Built on the Model Context Protocol for seamless integration with Claude and other MCP-compatible AI assistants
Enterprise-Ready — Rate limiting, caching, retry logic, multi-environment configs, and comprehensive error handling out of the box
Developer-Friendly — Built-in API exploration tools, schema inspection, and connection testing for rapid development
Type-Safe — Full TypeScript with Zod validation on every tool input

Key Features

| Feature | Description | |---------|-------------| | 143 MCP Tools | Complete coverage across 16 Maximo modules | | Dual Authentication | API Key and Username/Password (Basic Auth) support | | OSLC Query Engine | Full OSLC query support with a built-in query builder | | Bulk Operations | Batch create, update, delete, and process operations | | Analytics Dashboard | Work order summaries, asset health, PM compliance, and more | | Work Scheduling | Schedule management, conflict detection, backlog analysis | | Job Plan Management | Full CRUD with task, labor, material, and service planning | | Multi-Environment | Seamless switching between dev, test, staging, and production | | Smart Caching | In-memory cache with configurable TTL and size limits | | Rate Limiting | Token bucket algorithm prevents Maximo API throttling | | Retry Logic | Exponential backoff with configurable retry attempts | | Connection Pooling | HTTP keep-alive for sustained throughput | | Structured Logging | Winston-based logging with configurable levels | | Input Validation | Zod schemas validate every tool input at runtime |

Supported Modules

| Module | Tools | Key Operations | |--------|:-----:|----------------| | Work Orders | 15 | CRUD, status changes, labor/material/service assignment, tasks, work logs, close | | Purchase Orders | 15 | CRUD, line items, approval workflows, receiving, receipts | | Preventive Maintenance | 13 | CRUD, WO generation, job plans, scheduling, frequency, activate/deactivate | | Persons & Labor | 13 | Person management, crafts, labor transactions, crews, availability, cost summaries | | Assets | 12 | CRUD, meter readings, moves, hierarchy, specifications, downtime, status changes | | Service Requests | 12 | CRUD, status management, WO conversion, escalation, solutions, work logs | | Inventory | 11 | Items, issue/return/transfer, adjustments, reorder points, stock levels | | Job Plans | 11 | CRUD, tasks, labor/material/service requirements, linked work orders | | Analytics | 7 | WO summaries, asset health, inventory reports, PM compliance, dashboards | | Locations | 6 | CRUD, hierarchy navigation, search | | Dev Tools | 6 | Connection testing, API exploration, schema inspection, health checks, metadata | | Scheduling | 6 | Work schedules, unscheduled work, backlog, conflicts, upcoming PMs | | Query & Search | 4 | OSLC queries, advanced search, saved queries, query builder | | Bulk Operations | 4 | Bulk create, update, delete, batch processing | | Classifications | 4 | Classification trees, hierarchy, specifications, spec value updates | | Attachments | 4 | Upload, download, list, delete document attachments | | | 143 | |

Quick Start

Prerequisites

Node.js 18.0.0 or higher
npm 9.0.0 or higher
IBM Maximo MAS 9.x instance with REST API enabled
API key or credentials with appropriate permissions

Installation

From npm (recommended):

npm install -g maximo-mcp-server

From source:

git clone https://github.com/swetamshakula/maximo-mcp-server.git
cd maximo-mcp-server
npm install
npm run build

Configuration

Create a .env file in the project root:

# Required
MAXIMO_HOST=https://your-maximo-instance.com
MAXIMO_API_KEY=your-api-key-here

# Optional
MAXIMO_TIMEOUT=30000        # Request timeout in ms (default: 30000)
LOG_LEVEL=info              # debug | info | warn | error (default: info)
CACHE_ENABLED=true          # Enable response caching (default: false)

Multi-environment setup using config.json:

{
  "environments": {
    "dev": {
      "host": "https://dev-maximo.example.com",
      "apiKey": "${DEV_API_KEY}"
    },
    "staging": {
      "host": "https://staging-maximo.example.com",
      "apiKey": "${STAGING_API_KEY}"
    },
    "prod": {
      "host": "https://prod-maximo.example.com",
      "apiKey": "${PROD_API_KEY}"
    }
  },
  "defaultEnvironment": "dev"
}

Environment variables referenced as ${VAR_NAME} in config.json are interpolated at runtime from your shell environment or .env file.

Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "maximo": {
      "command": "node",
      "args": ["/path/to/maximo-mcp-server/dist/index.js"],
      "env": {
        "MAXIMO_HOST": "https://your-maximo-instance.com",
        "MAXIMO_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using npx (no local install needed):

{
  "mcpServers": {
    "maximo": {
      "command": "npx",
      "args": ["-y", "maximo-mcp-server"],
      "env": {
        "MAXIMO_HOST": "https://your-maximo-instance.com",
        "MAXIMO_API_KEY": "your-api-key-here"
      }
    }
  }
}

After saving, restart Claude Desktop. You should see the Maximo tools available in the tool picker.

Running Standalone

# Production
npm start

# Development with hot reload
npm run dev

# With custom config
maximo-mcp-server --config config.json

The server communicates over stdio using the MCP protocol. Use Claude Desktop, Claude Code, or any MCP-compatible client to interact with it.

Docker

The server ships with a production-ready Docker setup featuring multi-stage builds, non-root execution, and a read-only filesystem.

Quick Start with Docker

Build the image:

docker build -t maximo-mcp-server .

Run interactively (stdio mode):

docker run -i --rm \
  -e MAXIMO_HOST=https://your-maximo-instance.com \
  -e MAXIMO_API_KEY=your-api-key \
  maximo-mcp-server

The -i flag is required because MCP communicates over stdin/stdout.

Docker Compose

Production mode:

# Build and run (production — uses compiled dist/)
docker compose -f docker-compose.yml run --rm maximo-mcp

# Build image only
docker compose build

Development mode (auto-applied via override file):

# Runs ts-node with source mounting and debug logging
docker compose run --rm maximo-mcp

To run production-only (skip the dev override):

docker compose -f docker-compose.yml run --rm maximo-mcp

Environment variables can be set in .env or passed directly:

docker compose run --rm \
  -e MAXIMO_HOST=https://dev-maximo.example.com \
  -e MAXIMO_API_KEY=your-key \
  maximo-mcp

Claude Desktop with Docker

Configure Claude Desktop to use the Docker container:

{
  "mcpServers": {
    "maximo": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MAXIMO_HOST=https://your-maximo-instance.com",
        "-e", "MAXIMO_API_KEY=your-api-key",
        "maximo-mcp-server"
      ]
    }
  }
}

Docker Architecture

| Layer | Details | |-------|---------| | Base image | node:22-alpine (minimal footprint) | | Build strategy | Multi-stage — compile in stage 1, ship only dist/ in stage 2 | | Security | Non-root user (mcpuser:1001), read-only filesystem, no-new-privileges | | Health check | Verifies entry point is loadable every 30s | | Logs | Mounted volume at /app/logs | | Secrets | Never baked in — always passed as runtime env vars |

Usage Examples

Work Orders

Create a work order:

{
  "tool": "maximo_create_workorder",
  "arguments": {
    "description": "Repair centrifugal pump bearing failure",
    "assetnum": "PUMP-001",
    "location": "BR-300",
    "worktype": "CM",
    "priority": 2,
    "siteid": "BEDFORD"
  }
}

Search work orders with filters:

{
  "tool": "maximo_search_workorders",
  "arguments": {
    "where": "status=\"WAPPR\" and priority<=2",
    "select": "wonum,description,status,priority,reportdate",
    "orderBy": "+priority,-reportdate",
    "pageSize": 25
  }
}

Add labor to a work order:

{
  "tool": "maximo_add_labor",
  "arguments": {
    "wonum": "WO-1001",
    "laborcode": "SMITH",
    "craft": "ELECT",
    "hours": 4.5,
    "siteid": "BEDFORD"
  }
}

Change work order status:

{
  "tool": "maximo_change_workorder_status",
  "arguments": {
    "wonum": "WO-1001",
    "status": "APPR",
    "siteid": "BEDFORD"
  }
}

Assets

Record a meter reading:

{
  "tool": "maximo_record_meter",
  "arguments": {
    "assetnum": "PUMP-001",
    "metername": "RUNTIME",
    "newreading": 12500.5,
    "newreadingdate": "2026-02-20T10:00:00Z"
  }
}

Get asset hierarchy:

{
  "tool": "maximo_get_asset_hierarchy",
  "arguments": {
    "assetnum": "PLANT-A",
    "siteid": "BEDFORD"
  }
}

Check asset downtime:

{
  "tool": "maximo_get_asset_downtime",
  "arguments": {
    "assetnum": "CONV-200",
    "siteid": "BEDFORD"
  }
}

Inventory

Issue inventory:

{
  "tool": "maximo_issue_inventory",
  "arguments": {
    "itemnum": "BEARING-6205",
    "storeloc": "CENTRAL",
    "quantity": 2,
    "wonum": "WO-1001",
    "siteid": "BEDFORD"
  }
}

Check items below reorder point:

{
  "tool": "maximo_get_items_below_reorder",
  "arguments": {
    "storeloc": "CENTRAL",
    "siteid": "BEDFORD"
  }
}

Service Requests

Create and escalate a service request:

{
  "tool": "maximo_create_sr",
  "arguments": {
    "description": "HVAC system not cooling in Building A, Floor 3",
    "location": "BLD-A-FL3",
    "reportedby": "JSMITH",
    "siteid": "BEDFORD"
  }
}

{
  "tool": "maximo_escalate_sr",
  "arguments": {
    "ticketid": "SR-1042",
    "escalation_reason": "Affecting 50+ employees, temperature exceeding safe limits",
    "siteid": "BEDFORD"
  }
}

Convert service request to work order:

{
  "tool": "maximo_convert_sr_to_wo",
  "arguments": {
    "ticketid": "SR-1042",
    "siteid": "BEDFORD"
  }
}

Purchase Orders

Create a PO with line items:

{
  "tool": "maximo_create_po",
  "arguments": {
    "description": "Quarterly bearing stock replenishment",
    "vendor": "ACME-PARTS",
    "siteid": "BEDFORD"
  }
}

{
  "tool": "maximo_add_po_line",
  "arguments": {
    "ponum": "PO-4500",
    "itemnum": "BEARING-6205",
    "quantity": 50,
    "unitcost": 24.99,
    "siteid": "BEDFORD"
  }
}

Submit for approval and receive:

{
  "tool": "maximo_submit_po_approval",
  "arguments": { "ponum": "PO-4500", "siteid": "BEDFORD" }
}

{
  "tool": "maximo_receive_po_line",
  "arguments": {
    "ponum": "PO-4500",
    "polinenum": 1,
    "quantity": 50,
    "siteid": "BEDFORD"
  }
}

Preventive Maintenance

Generate work orders from a PM:

{
  "tool": "maximo_generate_pm_wo",
  "arguments": {
    "pmnum": "PM-PUMP-QUARTERLY",
    "siteid": "BEDFORD"
  }
}

Update PM frequency:

{
  "tool": "maximo_update_pm_frequency",
  "arguments": {
    "pmnum": "PM-PUMP-QUARTERLY",
    "frequency": 90,
    "frequnit": "DAYS",
    "siteid": "BEDFORD"
  }
}

Analytics & Reporting

Get a maintenance dashboard:

{
  "tool": "maximo_dashboard",
  "arguments": {
    "siteid": "BEDFORD"
  }
}

Check PM compliance:

{
  "tool": "maximo_pm_compliance",
  "arguments": {
    "siteid": "BEDFORD"
  }
}

Find overdue work orders:

{
  "tool": "maximo_overdue_workorders",
  "arguments": {
    "siteid": "BEDFORD"
  }
}

Identify top downtime assets:

{
  "tool": "maximo_top_downtime_assets",
  "arguments": {
    "siteid": "BEDFORD",
    "limit": 10
  }
}

OSLC Queries

Ad-hoc query with the OSLC engine:

{
  "tool": "maximo_query",
  "arguments": {
    "objectStructure": "mxwodetail",
    "select": "wonum,description,status,priority,assetnum,location",
    "where": "status in [\"WAPPR\",\"APPR\"] and worktype=\"CM\"",
    "orderBy": "+priority,-reportdate",
    "pageSize": 50
  }
}

Build a complex query interactively:

{
  "tool": "maximo_build_query",
  "arguments": {
    "objectStructure": "mxasset",
    "conditions": [
      { "field": "status", "operator": "=", "value": "OPERATING" },
      { "field": "assettype", "operator": "=", "value": "PRODUCTION" }
    ],
    "select": "assetnum,description,location,status",
    "orderBy": "+assetnum"
  }
}

Bulk Operations

Create multiple work orders in one call:

{
  "tool": "maximo_bulk_create",
  "arguments": {
    "objectStructure": "mxwodetail",
    "records": [
      { "description": "Monthly inspection - Line A", "worktype": "PM", "siteid": "BEDFORD" },
      { "description": "Monthly inspection - Line B", "worktype": "PM", "siteid": "BEDFORD" },
      { "description": "Monthly inspection - Line C", "worktype": "PM", "siteid": "BEDFORD" }
    ]
  }
}

Architecture

High-Level Design

┌──────────────────────────────────────────────────────────────────┐
│                    MCP Client (Claude / AI Assistant)             │
└───────────────────────────┬──────────────────────────────────────┘
                            │ MCP Protocol (stdio)
┌───────────────────────────▼──────────────────────────────────────┐
│                         MCP Server                                │
│                                                                   │
│  ┌──────────────┐  ┌───────────────┐  ┌────────────────────────┐ │
│  │ Auth Manager  │  │  Tool Router  │  │  Response Formatter    │ │
│  │  (API Key /   │  │  (143 tools)  │  │  (Normalize + Format)  │ │
│  │  Basic Auth)  │  │               │  │                        │ │
│  └──────────────┘  └───────────────┘  └────────────────────────┘ │
│                                                                   │
│  ┌──────────────┐  ┌───────────────┐  ┌────────────────────────┐ │
│  │ Rate Limiter  │  │    Cache      │  │   Error Handler        │ │
│  │ (Token Bucket)│  │  (TTL + Size) │  │  (Context-Aware)       │ │
│  └──────────────┘  └───────────────┘  └────────────────────────┘ │
└───────────────────────────┬──────────────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────────────┐
│                       Module Layer (16 modules)                   │
│                                                                   │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐        │
│  │Work Ord│ │ Assets │ │  Inv   │ │  S.R.  │ │  P.O.  │        │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘        │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐        │
│  │  P.M.  │ │ Plans  │ │Persons │ │  Locs  │ │ Class  │        │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘        │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐        │
│  │ Attach │ │Analytic│ │Schedule│ │ Query  │ │  Bulk  │        │
│  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘        │
│  ┌────────┐                                                      │
│  │DevTools│                                                      │
│  └────────┘                                                      │
└───────────────────────────┬──────────────────────────────────────┘
                            │ HTTPS (REST API)
┌───────────────────────────▼──────────────────────────────────────┐
│               IBM Maximo Application Suite 9.x                    │
│                      (OSLC REST API)                              │
└──────────────────────────────────────────────────────────────────┘

Module Structure

Every module follows a consistent five-file pattern:

src/modules/<module-name>/
├── operations.ts    # Business logic — makes HTTP calls via MaximoClient
├── tools.ts         # MCP tool definitions — name, description, schema, handler
├── types.ts         # TypeScript interfaces for requests and responses
├── validators.ts    # Zod schemas for runtime input validation
└── index.ts         # Public exports

Design principle: operations.ts owns the business logic; tools.ts is a thin MCP adapter. This separation allows operations to be reused by multiple tools, direct API calls, or future interfaces without duplication.

Project Structure

maximo-mcp-server/
├── src/
│   ├── index.ts                    # Server entry point & tool registration
│   ├── auth/                       # Authentication (API key + Basic Auth)
│   ├── config/                     # ConfigManager — env, JSON, interpolation
│   ├── core/                       # Infrastructure layer
│   │   ├── maximo-client.ts        #   HTTP client (retry, cache, rate limit)
│   │   ├── error-handler.ts        #   Error transformation & context
│   │   ├── response-formatter.ts   #   Response normalization
│   │   ├── rate-limiter.ts         #   Token bucket rate limiter
│   │   ├── cache-manager.ts        #   In-memory TTL cache
│   │   └── types.ts                #   Shared core type definitions
│   ├── modules/                    # 16 Maximo functional modules
│   │   ├── work-orders/            #   15 tools
│   │   ├── assets/                 #   12 tools
│   │   ├── inventory/              #   11 tools
│   │   ├── purchase-orders/        #   15 tools
│   │   ├── service-requests/       #   12 tools
│   │   ├── preventive-maintenance/ #   13 tools
│   │   ├── persons-labor/          #   13 tools
│   │   ├── plans/                  #   11 tools (Job Plans)
│   │   ├── analytics/              #    7 tools
│   │   ├── locations/              #    6 tools
│   │   ├── scheduler/              #    6 tools
│   │   ├── dev-tools/              #    6 tools
│   │   ├── query-search/           #    4 tools
│   │   ├── bulk-operations/        #    4 tools
│   │   ├── classifications/        #    4 tools
│   │   └── attachments/            #    4 tools
│   ├── utils/                      # Utility functions
│   ├── resources/                  # MCP resource definitions
│   └── tools/                      # Tool registry helpers
├── tests/
│   ├── unit/                       # Unit tests (per module)
│   ├── integration/                # Integration tests (mocked API)
│   └── fixtures/                   # Test data & mock responses
├── docs/
│   ├── planning/                   # Architecture, roadmap, tool catalog
│   └── api/                        # API guides, module documentation
├── dist/                           # Compiled output (git-ignored)
├── logs/                           # Runtime logs (git-ignored)
├── package.json
├── tsconfig.json
├── jest.config.js
└── .env                            # Environment config (git-ignored)

Core Infrastructure

| Component | Purpose | Implementation | |-----------|---------|----------------| | MaximoClient | HTTP communication with Maximo REST API | Axios with interceptors, keep-alive pooling | | AuthManager | Credential management and session handling | API Key headers or Basic Auth with session tokens | | RateLimiter | Prevent exceeding Maximo API limits | Token bucket algorithm with configurable windows | | CacheManager | Reduce redundant API calls | In-memory cache via node-cache with TTL and size limits | | ErrorHandler | Transform API errors into actionable messages | HTTP status mapping, context preservation, custom error classes | | ResponseFormatter | Normalize API responses | Consistent format, pagination metadata, OSLC parsing | | ConfigManager | Load and merge configuration sources | .env files, config.json, environment variable interpolation |

Configuration Reference

Environment Variables

| Variable | Required | Default | Description | |----------|:--------:|---------|-------------| | MAXIMO_HOST | Yes | — | Base URL of your Maximo instance | | MAXIMO_API_KEY | Yes* | — | API key for authentication | | MAXIMO_USERNAME | Yes* | — | Username (if using Basic Auth) | | MAXIMO_PASSWORD | Yes* | — | Password (if using Basic Auth) | | MAXIMO_TIMEOUT | No | 30000 | Request timeout in milliseconds | | LOG_LEVEL | No | info | Logging level: debug, info, warn, error | | CACHE_ENABLED | No | false | Enable in-memory response caching | | CACHE_TTL | No | 300 | Cache time-to-live in seconds | | CACHE_MAX_SIZE | No | 100 | Maximum cached entries |

* Provide either MAXIMO_API_KEY or MAXIMO_USERNAME + MAXIMO_PASSWORD.

Authentication Modes

API Key (recommended for automation):

apikey: your-api-key-here
Content-Type: application/json

Basic Auth (for development):

Authorization: Basic base64(username:password)
Content-Type: application/json

Development

Building from Source

# Install dependencies
npm install

# Build TypeScript to dist/
npm run build

# Build with esbuild bundle
npm run build:bundle

# Development mode with hot reload
npm run dev

# Clean build artifacts
npm run clean

Testing

# Run all tests
npm test

# Watch mode for development
npm run test:watch

# Coverage report (70% threshold enforced)
npm run test:coverage

# Single test file
npm test -- path/to/test.spec.ts

# Pattern matching
npm test -- --testNamePattern="WorkOrder"

Coverage thresholds (enforced in jest.config.js):

| Metric | Minimum | |--------|:-------:| | Branches | 70% | | Functions | 70% | | Lines | 70% | | Statements | 70% |

Code Quality

# Lint with ESLint
npm run lint

# Auto-fix lint issues
npm run lint:fix

# Format with Prettier
npm run format

# Type check without emitting
npm run type-check

Performance

| Feature | Implementation | Benefit | |---------|----------------|---------| | Response Caching | In-memory with TTL | Eliminates redundant API calls | | Connection Pooling | Axios keep-alive | Reuses TCP connections | | Rate Limiting | Token bucket algorithm | Prevents Maximo API throttling | | Retry with Backoff | Exponential (3 retries default) | Handles transient failures | | Bulk Operations | Batch API calls | Reduces round trips for multi-record operations | | Lazy Module Loading | On-demand initialization | Faster server startup |

Troubleshooting

Connection Issues

Problem: ECONNREFUSED or ETIMEDOUT when connecting to Maximo.

# Verify connectivity
curl -I https://your-maximo-instance.com/maximo/api/os

# Check your .env
echo $MAXIMO_HOST

Solutions:

Verify MAXIMO_HOST includes the full base URL with protocol (https://)
Check network/VPN connectivity to the Maximo server
Increase MAXIMO_TIMEOUT if the instance is slow to respond

Authentication Errors

Problem: 401 Unauthorized responses.

Solutions:

Verify your API key is valid and not expired
Ensure the API key has permissions for the Maximo object structures you're accessing
For Basic Auth, confirm the account is not locked or expired
Check that the apikey header name matches your Maximo configuration

OSLC Query Errors

Problem: 400 Bad Request on query operations.

Solutions:

Validate field names against your Maximo schema using maximo_inspect_schema
Enclose string values in double quotes: status="WAPPR" not status=WAPPR
Use maximo_build_query to construct queries interactively
Check OSLC where clause syntax — Maximo uses its own dialect

Rate Limiting

Problem: 429 Too Many Requests or throttled responses.

Solutions:

The built-in rate limiter should handle this automatically
If you're still hitting limits, reduce pageSize in queries
Avoid concurrent bulk operations against the same Maximo instance
Check your Maximo admin for rate limit configuration

Debug Mode

Enable verbose logging to diagnose issues:

LOG_LEVEL=debug npm run dev

Logs are written to the logs/ directory with structured JSON output. Sensitive data (API keys, passwords) is automatically sanitized.

FAQ

Which Maximo versions are supported?

This server is built for IBM Maximo Application Suite (MAS) 9.x and its OSLC-based REST API. It may work with Maximo 7.6.1.x instances that have the REST API enabled, but this is not officially tested.

Can I use this with Claude Desktop?

Yes. See the Claude Desktop Integration section for configuration instructions. The server communicates over stdio using the MCP protocol.

Does this modify data in Maximo?

Yes. Tools like maximo_create_workorder, maximo_update_asset, and maximo_delete_po perform write operations. Always test against a development or sandbox environment first.

How do I add a custom Maximo module?

Create a new directory under src/modules/
Follow the five-file pattern: operations.ts, tools.ts, types.ts, validators.ts, index.ts
Register the module in src/index.ts
Add tests under tests/unit/modules/ and tests/integration/modules/

See the Module Structure section for details.

What's the difference between maximo_query and maximo_advanced_search?

maximo_query executes raw OSLC queries with full control over where, select, orderBy, and pagination. maximo_advanced_search provides a higher-level interface with pre-built search patterns. Use maximo_build_query to construct complex OSLC queries interactively.

Can I run multiple instances for different environments?

Yes. Use config.json with multiple environment definitions and the defaultEnvironment setting. You can also run separate server processes with different .env files.

Security

Best Practices

Never commit credentials — Use .env files (git-ignored) or environment variables
Use API keys over passwords — API keys can be scoped and rotated independently
HTTPS only — All connections to Maximo should use TLS
Principle of least privilege — Use API keys with minimal required permissions
Rotate regularly — Implement key rotation policies
Audit logging — Enable LOG_LEVEL=info or higher in production
Input validation — All tool inputs are validated with Zod schemas before reaching Maximo

Reporting Vulnerabilities

If you discover a security vulnerability, please report it responsibly:

Do not open a public GitHub issue
Email swetamsh009@icloud.com with details
Include steps to reproduce, impact assessment, and suggested fix if possible
We will acknowledge receipt within 48 hours and provide a timeline for resolution

Contributing

We welcome contributions from the community. Here's how to get started:

Getting Started

Fork the repository
Clone your fork: git clone https://github.com/your-username/maximo-mcp-server.git
Branch from main: git checkout -b feature/your-feature-name
Install dependencies: npm install
Make your changes
Test your changes: npm test
Lint your code: npm run lint
Commit with a meaningful message
Push and open a Pull Request

Code Standards

TypeScript strict mode — All strict compiler options are enabled
Zod validation — All tool inputs must have Zod schemas in validators.ts
Test coverage — Maintain 70%+ coverage; new code should include tests
ESLint + Prettier — Run npm run lint and npm run format before committing
Conventional Commits — Use prefixes: feat:, fix:, docs:, refactor:, test:, chore:

Adding a New Module

Follow the Module Implementation Checklist:

Create src/modules/<name>/ with all five files
Implement operations against the Maximo OSLC API
Define MCP tools with descriptive names (maximo_<action>_<object>)
Add Zod validators for all tool inputs
Register in src/index.ts
Write unit + integration tests
Update this README's module table

Roadmap

v1.0 — Current

143 tools across 16 modules
Dual authentication (API Key + Basic Auth)
OSLC query engine with query builder
Analytics and scheduling modules
Bulk operations and batch processing
Comprehensive error handling, caching, and rate limiting

v1.1 — Planned

Webhook support for Maximo event notifications
Custom saved query management
Enhanced analytics with trend analysis
Tool usage metrics and telemetry

v2.0 — Future

GraphQL adapter layer
WebSocket support for real-time Maximo events
AI-powered query optimization
Predictive maintenance insights
Natural language to OSLC query translation

License

This project is licensed under the MIT License — see the LICENSE file for details.

Acknowledgments

IBM — for the Maximo Application Suite and its comprehensive REST API
Anthropic — for the Model Context Protocol specification
MCP Community — for the SDK, tooling, and ecosystem
All contributors who help improve this project

Back to Top

Built for the Maximo community — empowering developers to build better integrations through AI-assisted development.

IBM Maximo MAS 9.x MCP Server

The most comprehensive Model Context Protocol server for IBM Maximo Application Suite

Table of Contents

Overview

Why This Server?

Key Features

Supported Modules

Quick Start

Prerequisites

Installation

Configuration

Claude Desktop Integration

Running Standalone

Docker

Quick Start with Docker

Docker Compose

Claude Desktop with Docker

Docker Architecture

Usage Examples

Work Orders

Assets

Inventory

Service Requests

Purchase Orders

Preventive Maintenance

Analytics & Reporting

OSLC Queries

Bulk Operations

Architecture

High-Level Design

Module Structure

Project Structure

Core Infrastructure

Configuration Reference

Environment Variables

Authentication Modes

Development

Building from Source

Testing

Code Quality

Performance

Troubleshooting

Connection Issues

Authentication Errors

OSLC Query Errors

Rate Limiting

Debug Mode

FAQ

Security

Best Practices

Reporting Vulnerabilities

Contributing

Getting Started

Code Standards

Adding a New Module

Roadmap

v1.0 — Current

v1.1 — Planned

v2.0 — Future

License

Acknowledgments

Install Package (if required)

Cursor configuration (mcp.json)