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
   

2. Set environment variables:

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

3. Run the MCP server:

   python src/wlst_mcp.py
   

4. 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:

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

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

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.