WLST MCP Server

WLST MCP Server

A Model Context Protocol (MCP) server for Oracle WebLogic Server administration using WLST (WebLogic Scripting Tool).

Overview

This MCP server provides a comprehensive set of tools for managing Oracle WebLogic Server domains, including server lifecycle management, application deployment, monitoring, and diagnostics.

Project Structure

wlst-mcp/
├── src/
│   └── wlst_mcp.py          # Main MCP server implementation
├── README.md                 # This file - main documentation
├── ARCHITECTURE.md           # System architecture diagrams
├── INSTALLATION.md           # Prerequisites and installation guide
├── INTEGRATION.md            # Claude Desktop & Claude Code setup
├── EXAMPLES.md               # Usage examples and custom scripts
├── requirements.txt          # Python dependencies
├── LICENSE                   # Apache License 2.0
└── .gitignore               # Git ignore patterns

Quick Start

1. Install dependencies:

   pip install -r requirements.txt

1. Set environment variables:

   export WLST_ADMIN_URL=t3://localhost:7001
   export WLST_USERNAME=weblogic
   export WLST_PASSWORD=your_password

1. Run the MCP server:

   python src/wlst_mcp.py

1. Integrate with Claude: See INTEGRATION.md for detailed setup instructions.

Documentation

| Document | Description | |----------|-------------| | ARCHITECTURE.md | System architecture and component diagrams | | INSTALLATION.md | Prerequisites, installation, security configuration | | INTEGRATION.md | Claude Desktop & Claude Code integration | | EXAMPLES.md | Usage examples and custom WLST scripts |

Features

• Server Management: Start, stop, restart, and monitor WebLogic servers
• Application Deployment: Deploy, undeploy, and list applications
• Application Diagnostics: Diagnose failed applications with root cause analysis and remediation suggestions
• Monitoring: Real-time metrics for JVM, threads, JDBC, and JMS
• Diagnostics: Thread dumps, health checks, and log analysis
• Log Analysis: Analyze server and NodeManager logs to identify restart reasons, errors, and issues
• Resource Management: JDBC datasources and JMS resources
• Custom Scripting: Execute custom WLST/Jython scripts

Available Tools

Connection & Discovery

| Tool | Description | |------|-------------| | wlst_test_connection | Test connectivity to a WebLogic Admin Server | | wlst_list_servers | List all servers in a WebLogic domain with their status |

Server Lifecycle

| Tool | Description | |------|-------------| | wlst_start_server | Start a managed server | | wlst_stop_server | Stop a managed server (supports force option) | | wlst_restart_server | Restart a managed server |

Application Management

| Tool | Description | |------|-------------| | wlst_deploy | Deploy an application (WAR, EAR, JAR) | | wlst_undeploy | Undeploy an application | | wlst_start_application | Start a deployed application | | wlst_stop_application | Stop a running application (without undeploying) | | wlst_redeploy_application | Redeploy an application in place | | wlst_list_applications | List all deployed applications |

Monitoring & Metrics

| Tool | Description | |------|-------------| | wlst_server_health | Get health status of WebLogic servers | | wlst_server_metrics | Get detailed metrics (JVM, threads, JDBC, JMS) |

Resource Management

| Tool | Description | |------|-------------| | wlst_list_datasources | List all JDBC datasources | | wlst_list_jms_resources | List JMS servers, modules, queues, and topics |

Diagnostics

| Tool | Description | |------|-------------| | wlst_thread_dump | Capture thread dump for debugging | | wlst_analyze_logs | Analyze server and NodeManager logs to identify restart reasons and errors | | wlst_diagnose_application | Diagnose why an application is in FAILED state with root cause analysis | | wlst_execute_script | Execute custom WLST/Jython scripts |

Tool Reference

wlst_test_connection

Test connectivity to a WebLogic Admin Server.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | admin_url | string | No | Admin Server URL (e.g., t3://localhost:7001). Uses WLST_ADMIN_URL env var if not provided | | username | string | No | WebLogic admin username. Uses WLST_USERNAME env var if not provided | | password | string | No | WebLogic admin password. Uses WLST_PASSWORD env var if not provided | | timeout | integer | No | Connection timeout in seconds (10-600, default: 120) |

---

wlst_list_servers

List all servers in a WebLogic domain with their status.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | response_format | string | No | Output format: markdown or json (default: markdown) |

---

wlst_start_server

Start a managed server in a WebLogic domain.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | server_name | string | Yes | Name of the managed server to start | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | timeout | integer | No | Operation timeout in seconds (10-600, default: 120) |

---

wlst_stop_server

Stop a managed server in a WebLogic domain. Supports two shutdown modes:

• Graceful shutdown (default): Waits for active sessions to complete before stopping. This is safer for production environments but takes longer.
• Force shutdown: Stops the server immediately without waiting for sessions. Use when you need to stop quickly or the server is unresponsive.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | server_name | string | Yes | Name of the managed server to stop | | force | boolean | No | Force shutdown (immediate). If false, performs graceful shutdown waiting for sessions to complete. Default: false | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | timeout | integer | No | Operation timeout in seconds. Graceful shutdown may need longer timeout. (10-600, default: 300) |

Shutdown Modes Comparison: | Mode | Parameter | Behavior | Use Case | |------|-----------|----------|----------| | Graceful | force: false | Waits for sessions to complete | Production, scheduled maintenance | | Force | force: true | Immediate stop, sessions terminated | Emergency, unresponsive server |

---

wlst_restart_server

Restart a managed server in a WebLogic domain. Performs a stop followed by a start.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | server_name | string | Yes | Name of the managed server to restart | | force | boolean | No | Force shutdown during restart. If false, performs graceful shutdown waiting for sessions. Default: false | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | timeout | integer | No | Operation timeout in seconds. Graceful restart may need longer timeout. (10-600, default: 300) |

---

wlst_deploy

Deploy an application to WebLogic Server.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_name | string | Yes | Application name | | app_path | string | Yes | Path to the application archive (WAR, EAR, JAR) | | targets | string | No | Comma-separated list of target servers/clusters | | stage_mode | string | No | Deployment stage mode: stage, nostage, or external_stage (default: stage) | | plan_path | string | No | Path to deployment plan XML | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password |

---

wlst_undeploy

Undeploy an application from WebLogic Server.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_name | string | Yes | Name of the application to undeploy | | targets | string | No | Comma-separated list of target servers/clusters | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | timeout | integer | No | Operation timeout (10-600, default: 120) |

---

wlst_start_application

Start a deployed application in WebLogic Server. The application must be already deployed but in a stopped (STATE_PREPARED) state.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_name | string | Yes | Name of the application to start | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | timeout | integer | No | Operation timeout in seconds (10-600, default: 120) |

---

wlst_stop_application

Stop a running application in WebLogic Server without undeploying it. The application transitions from STATE_ACTIVE to STATE_PREPARED, allowing it to be started again later.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_name | string | Yes | Name of the application to stop | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | timeout | integer | No | Operation timeout in seconds (10-600, default: 120) |

Application States: | State | Description | |-------|-------------| | STATE_ACTIVE | Application is running and serving requests | | STATE_PREPARED | Application is deployed but stopped (not serving requests) |

---

wlst_redeploy_application

Redeploy an application in WebLogic Server. This updates the application in place without changing its configuration or targets. Useful for updating application code without a full undeploy/deploy cycle.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_name | string | Yes | Name of the application to redeploy | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | timeout | integer | No | Operation timeout in seconds (10-600, default: 120) |

---

wlst_list_applications

List all deployed applications in a WebLogic domain.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | response_format | string | No | Output format: markdown or json (default: markdown) |

---

wlst_server_health

Get health status of WebLogic servers.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | server_name | string | No | Specific server name (all servers if not specified) | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | response_format | string | No | Output format: markdown or json (default: markdown) |

---

wlst_server_metrics

Get detailed metrics for a WebLogic server.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | server_name | string | Yes | Server name to get metrics for | | metric_type | string | No | Type of metrics: all, jvm, threads, jdbc, jms (default: all) | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | response_format | string | No | Output format: markdown or json (default: markdown) |

---

wlst_list_datasources

List all JDBC datasources in a WebLogic domain.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | response_format | string | No | Output format: markdown or json (default: markdown) |

---

wlst_list_jms_resources

List all JMS resources in a WebLogic domain.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | response_format | string | No | Output format: markdown or json (default: markdown) |

---

wlst_thread_dump

Get a thread dump from a WebLogic server for debugging.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | server_name | string | Yes | Server name to get thread dump from | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password |

---

wlst_analyze_logs

Analyze WebLogic server logs to identify restart reasons, errors, and issues. This tool examines NodeManager logs, server logs, and stdout/stderr output to detect OutOfMemoryErrors, JVM crashes, auto-restart events, and other critical issues.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | server_name | string | Yes | Name of the server to analyze logs for | | days | integer | No | Number of days to analyze (how far back in time). Range: 1-30, default: 1 | | log_type | string | No | Type of logs to analyze: all, server, nodemanager, stdout (default: all) | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | response_format | string | No | Output format: markdown or json (default: markdown) |

Log Types: | Type | Description | |------|-------------| | all | Analyze all available logs (default) | | server | Server log only (<server_name>.log) | | nodemanager | NodeManager log only (nodemanager.log) | | stdout | Server stdout/stderr only (<server_name>.out) |

Detected Patterns: | Category | Patterns Detected | |----------|-------------------| | Restart Events | Server start/stop, auto-restart triggers, process crashes | | Memory Errors | OutOfMemoryError, StackOverflowError | | JVM Crashes | SIGSEGV, SIGKILL, SIGABRT signals | | WebLogic Errors | BEA-XXXXX error codes | | Warnings | Stuck threads, low memory, overload conditions |

---

wlst_diagnose_application

Diagnose why an application is in FAILED state or having issues. This tool performs comprehensive diagnostics including checking source files, analyzing logs, and providing remediation suggestions.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | app_name | string | No | Application name to diagnose. If not provided, diagnoses all applications in FAILED state | | check_logs | boolean | No | Search server logs for related errors (default: true) | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password | | response_format | string | No | Output format: markdown or json (default: markdown) |

Diagnostics Performed: | Check | Description | |-------|-------------| | State Analysis | Compares current runtime state vs intended state for each target | | Source File Check | Verifies the application archive (WAR/EAR) exists on the filesystem | | Staging Check | Verifies staged files exist for applications using stage mode | | Log Analysis | Searches server and AdminServer logs for related errors | | Pattern Detection | Identifies common issues (ClassNotFound, OutOfMemory, connection errors) |

Issues Detected: | Issue Code | Description | |------------|-------------| | SOURCE_FILE_MISSING | The application WAR/EAR file does not exist at the configured path | | STAGING_MISSING | Staged files not found in the server's stage directory | | CLASS_NOT_FOUND | Missing class or JAR dependency (ClassNotFoundException) | | OUT_OF_MEMORY | JVM ran out of memory during deployment | | CONNECTION_ERROR | Network or database connection issue during startup | | DUPLICATE_RESOURCE | Duplicate JNDI name or resource conflict |

Example Output: ```markdown

Application Diagnostics Report

Summary

• Applications Analyzed: 1
• Applications in FAILED State: 1
• Total Issues Found: 1

🔴 simpleservlet

State

• 🔴 test_server1: STATE_FAILED
• Intended State: STATE_ACTIVE

Source File

• Path: servers\AdminServer\upload\simpleservlet\app\simpleservlet.war
• ❌ File Exists: No

Issues Found

• ❌ Source file (WAR/EAR) not found on filesystem

Probable Causes

• The application source file (WAR/EAR) does not exist at the configured path

Recommendations

1. Re-deploy the application with a valid source file path
2. Or copy the application archive to the expected location

---

### wlst_execute_script

Execute a custom WLST/Jython script.

**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `script` | string | **Yes** | WLST/Jython script to execute |
| `admin_url` | string | No | Admin Server URL (optional for offline scripts) |
| `username` | string | No | WebLogic admin username |
| `password` | string | No | WebLogic admin password |
| `timeout` | integer | No | Script execution timeout (10-1800, default: 120) |

## Configuration & Environment Variables

### How Credentials Are Resolved

The MCP server uses a **fallback mechanism** to resolve connection parameters. For each parameter, it checks in the following order:

1. Tool parameter (if provided) → 2. Environment variable → 3. Error (if required)

This means:
- If you provide a parameter in the tool call, it will be used
- If the parameter is not provided, the environment variable is used as default
- If neither is available, an error is returned for required parameters

### Environment Variables Reference

| Variable | Description | Example |
|----------|-------------|---------|
| `WLST_ADMIN_URL` | WebLogic Admin Server URL (protocol://host:port) | `t3://localhost:7001` |
| `WLST_USERNAME` | WebLogic admin username | `weblogic` |
| `WLST_PASSWORD` | WebLogic admin password | `welcome1` |

### URL Format

The `WLST_ADMIN_URL` must follow this format:

<protocol>://<host>:<port> ```

| Component | Description | Examples | |-----------|-------------|----------| | protocol | Connection protocol | t3, t3s, http, https | | host | Admin Server hostname or IP | localhost, 192.168.1.100, admin.example.com | | port | Admin Server listen port | 7001 (default), 7002 (SSL) |

Examples: ```bash

Local development (non-SSL)

WLST_ADMIN_URL=t3://localhost:7001

Local development (SSL)

WLST_ADMIN_URL=t3s://localhost:7002

Remote server

WLST_ADMIN_URL=t3s://weblogic-admin.example.com:7002

Using IP address

WLST_ADMIN_URL=t3://192.168.1.100:7001 ```

Configuration Examples

Option 1: Environment Variables (Recommended)

Set environment variables before starting the MCP server:

Linux/macOS: ``bash export WLST_ADMIN_URL=t3://localhost:7001 export WLST_USERNAME=weblogic export WLST_PASSWORD=your_password ``

Windows (Command Prompt): ``cmd set WLST_ADMIN_URL=t3://localhost:7001 set WLST_USERNAME=weblogic set WLST_PASSWORD=your_password ``

Windows (PowerShell): ``powershell $env:WLST_ADMIN_URL = "t3://localhost:7001" $env:WLST_USERNAME = "weblogic" $env:WLST_PASSWORD = "your_password" ``

Once configured, you can call tools without specifying connection parameters:

{
  "tool": "wlst_list_servers",
  "params": {}
}

Option 2: Tool Parameters (Override)

You can override environment variables by passing parameters directly:

{
  "tool": "wlst_list_servers",
  "params": {
    "admin_url": "t3://production-server:7001",
    "username": "admin_user",
    "password": "admin_password"
  }
}

Option 3: Claude Desktop Configuration

Configure in claude_desktop_config.json:

{
  "mcpServers": {
    "wlst-mcp": {
      "command": "python",
      "args": ["/path/to/wlst-mcp/server.py"],
      "env": {
        "WLST_ADMIN_URL": "t3://localhost:7001",
        "WLST_USERNAME": "weblogic",
        "WLST_PASSWORD": "your_password"
      }
    }
  }
}

Parameter Priority Example

Given this configuration:

# Environment variables
export WLST_ADMIN_URL=t3://dev-server:7001
export WLST_USERNAME=dev_user
export WLST_PASSWORD=dev_password

And this tool call:

{
  "tool": "wlst_list_servers",
  "params": {
    "admin_url": "t3://prod-server:7001"
  }
}

The resolved values will be: | Parameter | Value | Source | |-----------|-------|--------| | admin_url | t3://prod-server:7001 | Tool parameter (override) | | username | dev_user | Environment variable (fallback) | | password | dev_password | Environment variable (fallback) |

Response Formats

Most tools support two output formats:

• markdown: Human-readable formatted output (default)
• json: Machine-readable JSON output for programmatic use

License

Apache License 2.0 - See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.