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
• Monitoring: Real-time metrics for JVM, threads, JDBC, and JMS
• Diagnostics: Thread dumps and health checks
• 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_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_create_datasource | Create a generic JDBC datasource | | wlst_list_jms_resources | List JMS servers, modules, queues, and topics |

Diagnostics

| Tool | Description | |------|-------------| | wlst_thread_dump | Capture thread dump for debugging | | 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_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_create_datasource

Create a generic JDBC datasource in a WebLogic domain.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | ds_name | string | Yes | Datasource name | | jndi_name | string | Yes | JNDI name (e.g., jdbc/myDS) | | db_url | string | Yes | Database JDBC URL | | db_driver | string | Yes | JDBC driver class name | | db_user | string | Yes | Database username | | db_password | string | Yes | Database password | | targets | string | Yes | Comma-separated list of target servers/clusters | | min_capacity | integer | No | Minimum pool capacity (0-100, default: 1) | | max_capacity | integer | No | Maximum pool capacity (1-500, default: 15) | | admin_url | string | No | Admin Server URL | | username | string | No | WebLogic admin username | | password | string | No | WebLogic admin password |

---

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_execute_script

Execute a custom WLST/Jython script.

Security warning: this tool runs arbitrary caller-supplied code with no sandboxing — anyone who can call it can run arbitrary Jython (and, by extension, arbitrary OS commands) as the user running this MCP server. It is disabled by default and only registered when the WLST_ALLOW_EXECUTE_SCRIPT environment variable is set (see below). Use dry_run to preview what a script would do before actually running it.

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) | | dry_run | boolean | No | If true, return the script that would run without executing it (default: false) |

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 | | WLST_ALLOW_EXECUTE_SCRIPT | Opt-in flag to register wlst_execute_script (arbitrary code execution). Unset/empty = disabled. | true |

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

Known Limitations

wlst_analyze_logs and wlst_diagnose_application read raw log/source files from disk in addition to querying WebLogic MBeans. cmo.getRootDirectory() returns the domain home path as known to the Admin Server, but the file reads happen on whatever host actually runs the wlst.sh/wlst.cmd subprocess — i.e. the host running this MCP server, not necessarily the Admin Server. These checks only work if:

• this MCP server runs on the same host as the Admin Server, or
• the domain directory is mounted at the identical path on this MCP server's host (e.g. shared/NFS storage).

If neither is true, both tools detect this (domain_home_accessible: false in their JSON output) and surface an explicit warning instead of silently reporting "no issues found" or a false "source file missing".

License

Apache License 2.0 - See LICENSE for details.

Contributing

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