weblogic-mcp

wls-mcp

An MCP server that exposes a small, audited slice of the Oracle WebLogic Server REST management API to an AI agent — four tools, a least-privilege service account, and a JSON audit record for every call.

Built and verified against WebLogic Server 15.1.1.0 (Generic, JDK 21, Oracle Linux 9) running in Docker.

Why WebLogic, why now

Oracle removed the browser-based WebLogic Administration Console in 14.1.2, and 15.1.1 ships without it. Day-to-day administration is REST, WLST, or the separate WebLogic Remote Console. That makes WebLogic a natural fit for MCP: the management surface is already an HTTP API, so this server is a thin, explicit wrapper rather than screen-scraping — and the interesting work is in scoping and auditing it, not in plumbing.

Tools

Tool	Reads	Notes
list_servers	serverLifeCycleRuntimes + edit/servers	Every configured server with state, port, machine. The only view that includes stopped servers.
get_server_health	serverRuntimes/{name}	Health state, failed subsystem, symptoms. Returns lifecycle state instead when the server is not RUNNING.
get_jvm_stats	serverRuntimes/{name}/JVMRuntime	Heap current/max/free, free %, uptime, Java version. Bytes converted to MB.
control_server	serverLifeCycleRuntimes/{name}/{action}	start, shutdown, force_shutdown, via Node Manager. Destructive; see guardrails.

Three WebLogic behaviours the tool contracts are built around:

1. serverRuntimes only contains RUNNING servers. A stopped server is absent entirely — not present with state: SHUTDOWN. So listing servers must read serverLifeCycleRuntimes, while health and JVM stats read serverRuntimes.
2. serverRuntimes can be briefly empty while a managed server registers with the domain runtime service. "No runtime record" means not currently running, not error.
3. X-Requested-By is mandatory on state-changing requests; WebLogic rejects them as CSRF otherwise. The header value is arbitrary — its presence is the point.

Guardrails

control_server is the only tool that changes anything, and it is fenced:

• Least-privilege account. The server authenticates as a dedicated WebLogic user in the Operators and Monitors groups — never the domain administrator. That account can read runtime state and drive server lifecycle, and is refused when it tries to open a configuration edit session or create resources (verified: 403 on both).
• Allowlist. WLS_ALLOWED_SERVERS restricts which servers are addressable at all. Unset means the whole domain.
• Read-only mode. WLS_READ_ONLY=true disables control_server outright.
• Administration Server confirmation. Stopping the AdminServer also stops the REST API this server depends on, so nothing here can start it again. It requires confirm=true, and the response carries the host-level recovery command. WLS_ALLOW_ADMIN_SHUTDOWN=false forbids it entirely.
• No retry on lifecycle calls. GETs retry with capped exponential backoff; start and shutdown are sent exactly once.

Audit trail

Every invocation emits exactly one JSON record, on success, refusal, or error:

{"ts":"2026-09-13T12:41:07.882Z","tool":"control_server","principal":"wlsmcp",
 "target":"ms1","arguments":{"server_name":"ms1","action":"shutdown","confirm":false},
 "outcome":"success","duration_ms":9183}

Records go to stderr, and to WLS_AUDIT_LOG as JSON Lines if set. Nothing is ever written to stdout — under the stdio transport, stdout is the MCP protocol channel, and a stray print corrupts the session.

Install

uv venv && uv pip install -e .
cp .env.example .env   # then fill in WLS_PASSWORD

Run

Stdio, for a local client:

wls-mcp

Streamable HTTP, to serve a client on another machine:

wls-mcp --transport streamable-http --host 0.0.0.0 --port 8765

Over HTTP the server has no authentication of its own — put it behind a reverse proxy that terminates TLS and checks a bearer token, or keep it on a private network.

Wiring it into a client

Codex CLI

codex mcp add weblogic \
  --env WLS_BASE_URL=http://localhost:7001 \
  --env WLS_USERNAME=wlsmcp \
  --env WLS_PASSWORD=... \
  -- /path/to/.venv/bin/wls-mcp

or over HTTP:

codex mcp add weblogic --url http://host:8765/mcp --bearer-token-env-var WLS_MCP_TOKEN

Claude Code

claude mcp add weblogic --env WLS_USERNAME=wlsmcp --env WLS_PASSWORD=... -- /path/to/.venv/bin/wls-mcp

Configuration

See .env.example. Credentials are read only from the environment, never from argv, so they do not show up in ps.

Tests

uv pip install -e ".[dev]" && pytest

Unit tests mock the WebLogic REST API with respx; no live server needed.

Licence

MIT. The Oracle WebLogic Server binaries are not included or redistributed here — you pull Oracle's image yourself after accepting the licence on Oracle Container Registry. See ../RUNBOOK.md for the full domain build.