You can use the MCP Maximo Server to access IBM Maximo APIs through MCP Tools and expose them to AI applications like Dify Agent. It provides asset, work order, and inventory management tools, with reliable transport, caching, rate limiting, structured logging, and health checks to keep Maximo load manageable while giving you convenient programmatic access.

How to use

You will connect an MCP client to the server using an MCP configuration. The server exposes three tool families: Asset Management, Work Order Management, and Inventory Management. With these tools you can query assets, search and create work orders, and manage inventory items. The server supports a robust set of features like caching, health checks, and structured logs to help you monitor and optimize usage.

How to install

# Prerequisites
- Docker
- Docker Compose
- Maximo API Key (generated in Maximo)
- Secure MCP API Key for client connections

# Step 1. Clone the project
git clone <repository-url>
cd mcp-maximo-server

# Step 2. Configure environment
cp .env.example .env

{ In your .env, define: MCP_API_KEY=your-secure-mcp-api-key-here MAXIMO_API_URL=https://maximo.yourcompany.com/maximo MAXIMO_API_KEY=your-maximo-api-key-here }

Step 3. Start the service

docker-compose up -d

Step 4. Validate health

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "cache": "healthy",
  "maximo": "healthy",
  "version": "1.0.0",
  "environment": "production"
}

Step 5. Open test page

• Visit http://localhost:8000/
• Or http://localhost:8000/test

## Configuration and usage notes

You configure how clients connect using MCP server configurations. The server can be accessed via HTTP or via a local stdio (socket-like) setup depending on your integration. The most common setup is HTTP with SSE transport for live MCP streams. You will provide an MCP API key to your client and target the server URL.

Dify integration example (HTTP/SSE)

{ "mcpServers": { "maximo": { "url": "http://your-server-host:8000", "transport": "sse", "headers": { "Authorization": "Bearer YOUR_MCP_API_KEY" } } } }

Alternative HTTP transport example (explicit /mcp path)

{ "mcpServers": { "maximo": { "url": "http://your-server-host:8000/mcp", "transport": "http", "headers": { "Authorization": "Bearer YOUR_MCP_API_KEY" } } } }

Important: Ensure the MCP API key you use matches the key defined in your environment. Replace your-server-host:8000 with your actual server address.

Security and monitoring

Security and observability are built into the MCP Maximo Server. You will use two-layer API key authentication: one for Dify to MCP access and another for MCP to Maximo access. The server uses Redis for caching, a token bucket implementation for rate limiting, and structured JSON logs that include a correlation ID for tracing requests. Health checks monitor both Maximo and Redis connections.

Key security practices you should follow:

• Use strong API keys and rotate them periodically.
• Enable HTTPS in production with TLS.
• Restrict CORS to trusted origins.
• Use a Secrets Manager to store sensitive data.

Troubleshooting

If you encounter issues, check the following areas:

• Maximo connection: verify MAXIMO_API_URL and MAXIMO_API_KEY are correct and that the Maximo API is enabled.
• Redis connection: confirm the Redis container is running and reachable from the MCP server.
• MCP connectivity: verify the MCP server URL is reachable and the MCP_API_KEY in your environment matches the one configured in your client.

Common endpoints to verify health and status:

• Health: /health
• Logs: docker-compose logs -f mcp-server
• Logs tail: docker-compose logs --tail=100 mcp-server

Available tools

get_asset

Query asset details by asset number and site ID to retrieve comprehensive asset data.

search_assets

Search assets with filters such as status, location, and other criteria to find matching assets.

create_asset

Create a new asset with details like asset number, site, description, and type.

update_asset_status

Update the status of an asset and optionally add a memo for traceability.

get_work_order

Retrieve detailed information about a specific work order by number and site.

search_work_orders

Search work orders by status, work type, asset, and related fields.

create_work_order

Create a new work order with description, site, asset, and priority.

update_work_order_status

Change the status of a work order and add notes if needed.

get_inventory

Query inventory items by item number, site, and location.

search_inventory

Search inventory with criteria including low stock and location filters.

issue_inventory

Issue a quantity of inventory to a work order or other destination.