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

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

Server Lifecycle

Application Management

Monitoring & Metrics

Resource Management

Diagnostics

Tool Reference

wlst_test_connection

Test connectivity to a WebLogic Admin Server.

Parameters:

wlst_list_servers

List all servers in a WebLogic domain with their status.

Parameters:

wlst_start_server

Start a managed server in a WebLogic domain.

Parameters:

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:

Shutdown Modes Comparison:

wlst_restart_server

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

Parameters:

wlst_deploy

Deploy an application to WebLogic Server.

Parameters:

wlst_undeploy

Undeploy an application from WebLogic Server.

Parameters:

wlst_start_application

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

Parameters:

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:

Application States:

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:

wlst_list_applications

List all deployed applications in a WebLogic domain.

Parameters:

wlst_server_health

Get health status of WebLogic servers.

Parameters:

wlst_server_metrics

Get detailed metrics for a WebLogic server.

Parameters:

wlst_list_datasources

List all JDBC datasources in a WebLogic domain.

Parameters:

wlst_list_jms_resources

List all JMS resources in a WebLogic domain.

Parameters:

wlst_thread_dump

Get a thread dump from a WebLogic server for debugging.

Parameters:

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:

Log Types:

Detected Patterns:

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:

Diagnostics Performed:

Issues Detected:

Example Output:

# 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:

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

URL Format

The WLST_ADMIN_URL must follow this format:

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

Examples:

# 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:

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

Windows (Command Prompt):

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

Windows (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:

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.