Maximo Job Plan Management via MCP

This project uses the Model Context Protocol (MCP) to interact with IBM Maximo for job plan management.

Overview

The Maximo Job Plan MCP Server provides a seamless interface for AI assistants to interact with IBM Maximo's job plan management system. It enables natural language interactions for creating, querying, updating, and deleting job plans.

Features

• Import Job Plans: Bulk import job plans from CSV files
• List Job Plans: Query and filter job plans with OSLC queries
• Get Job Plan Details: Retrieve detailed information about specific job plans
• Delete Job Plans: Remove job plans from the system
• Natural Language Interface: Use conversational commands through AI assistants

Available MCP Tools

The maximo-jobplan MCP server provides 4 tools for managing job plans:

1. import_jobplans

Import job plans from CSV data into Maximo.

Example usage:

"Import job plans from jobplanMaximo.csv"

CSV Format:

JPNUM,DESCRIPTION,JPDURATION,STATUS,JOBTYPE,PLUSCJPREVNUM
HVAC-PM-001,Quarterly HVAC System Inspection,4.0,ACTIVE,PM,0

2. list_jobplans

List all job plans from Maximo with optional filtering.

Example usage:

"List all job plans"
"Show me HVAC job plans"

3. get_jobplan

Get detailed information about a specific job plan.

Example usage:

"Get details of job plan HVAC-PM-001"
"Show me the BREAKINSP job plan"

4. delete_jobplan

Delete a job plan by number.

Example usage:

"Delete job plan TEST-001"

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Access to IBM Maximo instance
• Maximo API key

Setup Steps

1. Clone the repository

   git clone <repository-url>
   cd maximo-jobplan-mcp
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Configure environment variables

   Set the following environment variables:

   • MAXIMO_BASE_URL: Your Maximo instance URL (e.g., https://your-maximo-instance.com)
   • MAXIMO_API_KEY: Your Maximo API key

5. Configure MCP Client

   For Bob/Claude Desktop, add to your MCP settings:

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

Project Structure

maximo-jobplan-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── build/                # Compiled JavaScript output
├── docs/                 # Documentation files
│   ├── MCP_SETUP_GUIDE.md
│   ├── QUICK_START.md
│   └── README_MAXIMO_CONNECTION.md
├── examples/
│   └── jobplanMaximo.csv # Sample job plans
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md

Usage Examples

Using with AI Assistants

Simply use natural language commands:

• "List all job plans in Maximo"
• "Show me details of HVAC-PM-001"
• "Import the job plans from the CSV file"
• "Get all PUMP job plans"
• "Delete job plan TEST-001"

Programmatic Usage

// The MCP server handles all interactions through the protocol
// No direct API calls needed when using with MCP clients

Configuration

Maximo Connection

The server connects to Maximo using:

• Base URL: Configured via MAXIMO_BASE_URL environment variable
• Authentication: API key via MAXIMO_API_KEY environment variable
• API Endpoint: /maximo/api/os/MXAPIJOBPLAN

CSV Import Format

Job plans CSV must include these columns:

• JPNUM: Job plan number (max 12 characters)
• DESCRIPTION: Job plan description
• JPDURATION: Duration in hours
• STATUS: Status (e.g., ACTIVE, INACTIVE)
• JOBTYPE: Job type (e.g., PM, CM)
• PLUSCJPREVNUM: Revision number

Development

Build Commands

# Build the project
npm run build

# Watch mode for development
npm run watch

# Prepare for distribution
npm run prepare

Testing

Test the MCP server connection:

node build/index.js

Troubleshooting

Connection Issues

1. Verify environment variables are set correctly
2. Check Maximo URL is accessible
3. Validate API key has proper permissions
4. Review SSL certificates (development mode disables SSL verification)

Import Failures

1. Check CSV format matches required columns
2. Verify job plan numbers are 12 characters or less
3. Ensure required fields are populated
4. Check for duplicate job plan numbers

Security Considerations

⚠️ Important Security Notes:

1. SSL Verification: Currently disabled for development. Enable for production:

   httpsAgent: new https.Agent({
     rejectUnauthorized: true  // Enable SSL verification
   })
   

2. API Key Storage: Store API keys securely using:

   • Environment variables
   • Secret management systems
   • Encrypted configuration files

3. Access Control: Ensure only authorized users can access the MCP server

License

MIT License - See LICENSE file for details