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.
- Overview
- Supported Modules
- Quick Start
- Docker
- Usage Examples
- Architecture
- Configuration Reference
- Development
- Performance
- Troubleshooting
- FAQ
- Security
- Contributing
- Roadmap
- License
- Acknowledgments
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.
- 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
| 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 |
| 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 |
- 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
From npm (recommended):
npm install -g maximo-mcp-serverFrom source:
git clone https://github.com/swetamshakula/maximo-mcp-server.git
cd maximo-mcp-server
npm install
npm run buildCreate 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}inconfig.jsonare interpolated at runtime from your shell environment or.envfile.
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.
# Production
npm start
# Development with hot reload
npm run dev
# With custom config
maximo-mcp-server --config config.jsonThe server communicates over stdio using the MCP protocol. Use Claude Desktop, Claude Code, or any MCP-compatible client to interact with it.
The server ships with a production-ready Docker setup featuring multi-stage builds, non-root execution, and a read-only filesystem.
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-serverThe
-iflag is required because MCP communicates over stdin/stdout.
Production mode:
# Build and run (production — uses compiled dist/)
docker compose -f docker-compose.yml run --rm maximo-mcp
# Build image only
docker compose buildDevelopment mode (auto-applied via override file):
# Runs ts-node with source mounting and debug logging
docker compose run --rm maximo-mcpTo run production-only (skip the dev override):
docker compose -f docker-compose.yml run --rm maximo-mcpEnvironment 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-mcpConfigure 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"
]
}
}
}| 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 |
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"
}
}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"
}
}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"
}
}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"
}
}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"
}
}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"
}
}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
}
}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"
}
}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" }
]
}
}┌──────────────────────────────────────────────────────────────────┐
│ 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) │
└──────────────────────────────────────────────────────────────────┘
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.
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)
| 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 |
| 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_KEYorMAXIMO_USERNAME+MAXIMO_PASSWORD.
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
# 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# 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% |
# 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| 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 |
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_HOSTSolutions:
- Verify
MAXIMO_HOSTincludes the full base URL with protocol (https://) - Check network/VPN connectivity to the Maximo server
- Increase
MAXIMO_TIMEOUTif the instance is slow to respond
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
apikeyheader name matches your Maximo configuration
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"notstatus=WAPPR - Use
maximo_build_queryto construct queries interactively - Check OSLC
whereclause syntax — Maximo uses its own dialect
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
pageSizein queries - Avoid concurrent bulk operations against the same Maximo instance
- Check your Maximo admin for rate limit configuration
Enable verbose logging to diagnose issues:
LOG_LEVEL=debug npm run devLogs are written to the logs/ directory with structured JSON output. Sensitive data (API keys, passwords) is automatically sanitized.
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/andtests/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.
- Never commit credentials — Use
.envfiles (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=infoor higher in production - Input validation — All tool inputs are validated with Zod schemas before reaching Maximo
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
We welcome contributions from the community. Here's how to get 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
- 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 lintandnpm run formatbefore committing - Conventional Commits — Use prefixes:
feat:,fix:,docs:,refactor:,test:,chore:
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
- 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
- Webhook support for Maximo event notifications
- Custom saved query management
- Enhanced analytics with trend analysis
- Tool usage metrics and telemetry
- GraphQL adapter layer
- WebSocket support for real-time Maximo events
- AI-powered query optimization
- Predictive maintenance insights
- Natural language to OSLC query translation
This project is licensed under the MIT License — see the LICENSE file for details.
- 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
Built for the Maximo community — empowering developers to build better integrations through AI-assisted development.