mcp-javamelody

An MCP (Model Context Protocol) server that gives read-only access to JavaMelody monitoring data for one or more Java web applications — HTTP/SQL/Spring counters, JVM info, thread dumps, database reports — straight from the agent, no manual dashboard digging. Only format=json GET requests against JavaMelody's own monitoring endpoint are made; nothing is ever written back to the monitored app.

How it works

• server.js — the MCP server. Reads a TOML config file listing your microservices (name, URL, optional basic-auth credentials), then exposes tools that call each one's JavaMelody ?format=json endpoint over plain HTTP(S).

• One server process covers all microservices in your config — pass a server argument to pick which one a tool call targets. Call list_servers first to see the valid names.

This tool is installed once and configured per project (one config file + one agent config entry per project, or one per environment if you want them separate). See Running multiple projects in parallel at the end.

Related MCP server: sonarqube-api-mcp

1. Prerequisite: JavaMelody must be enabled on the app, with JSON export

The target application needs the JavaMelody monitoring servlet/filter already installed and reachable, e.g. http://your-host:8080/your-app/monitoring. If it's protected with basic auth (recommended), have the username/password handy — see JavaMelody's own docs for enabling it and securing the endpoint.

JavaMelody's ?format=json export (used by every tool in this server) requires XStream on the monitored app's classpath — it's an optional dependency JavaMelody doesn't bundle by default. Add it to the app's own pom.xml:

<dependency>
    <groupId>com.thoughtworks.xstream</groupId>
    <artifactId>xstream</artifactId>
    <version>1.4.21</version>
</dependency>

Without it, ?format=json requests fail even though the regular HTML monitoring page works fine.

2. Client install

Requires Node.js 20+.

Windows / Linux / macOS — same steps:

Installs the mcp-javamelody command globally

npm install -g mcp-javamelody

Copy config.example.toml to a config file for the project, e.g. config.myproject.toml:

[[servers]]
name = "microservice1"
url = "http://localhost:8080/microservice1/monitoring"
user = "monitor"
password = "change-me"

[[servers]]
name = "microservice2"
url = "http://localhost:8080/microservice2/monitoring"
user = "monitor"
password = "change-me"

# Optional, top-level defaults applied to every server unless overridden per-server below.
# insecure = true       # accept self-signed https certificates
# timeout_ms = 30000    # request timeout (ms), default 30000

Each [[servers]] entry is one JavaMelody-monitored microservice, selected by name when calling a tool. user/ password are optional (omit for an unprotected endpoint). Keep this file out of any git repo if it holds real credentials — .gitignore already excludes config*.toml other than the example.

Sanity-check it works before wiring it with the agent:

mcp-javamelody --config-file /path/to/config.myproject.toml

It should print [Ready] JavaMelody MCP server ready — servers: ... to stderr and then sit waiting for input — Ctrl+C to stop.

3. Add it to Claude

Edit your Claude Desktop / Claude Code MCP config (create the file if it doesn't exist):

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

The same block on every OS — only the --config-file path syntax differs:

Windows:

{
  "mcpServers": {
    "myproject-javamelody": {
      "command": "mcp-javamelody",
      "args": [
        "--config-file",
        "C:\\Users\\you\\config.myproject.toml"
      ]
    }
  }
}

Linux / macOS:

{
  "mcpServers": {
    "myproject-javamelody": {
      "command": "mcp-javamelody",
      "args": [
        "--config-file",
        "/home/you/config.myproject.toml"
      ]
    }
  }
}

Restart Claude. You should see tools like list_servers, get_counter_stats, get_statistics, get_part, list_database_requests and get_database_stats available under myproject-javamelody.

Prefer running from a local checkout instead of a global installation? git clone the repo, npm install, then use "command": "node" with "args": ["/path/to/server.js", "--config-file", "/path/to/config.toml"] — both invocation styles read the same config file.

Available tools

• list_servers — list the configured microservices. Call first to get valid server values.

• get_counter_stats — per-request aggregates for a date range: hits, mean/max/total duration, errors, one row per URL / SQL statement / Spring method / error / log message. The most granular way to find what's slow or failing.

• get_statistics — full overview for a date range: all counters plus JVM info in one response.

• get_part — live snapshot right now, no date range: JVM/host info, open JDBC connections, current requests, all threads, JMX MBeans, OS processes, JNDI tree.

• list_database_requests — list the database report names/indexes available (depends on the JDBC driver), call before get_database_stats.

• get_database_stats — a database report for a date range, e.g. pg_stat_activity, pg_locks, pg_stat_user_tables, pg_settings.

Running multiple projects in parallel

The whole setup above is designed to be repeated per project or environment, side by side, without collisions:

• Config files: config.<project>.toml or config.<project>-<environment>.toml, one per agent config entry (remember to gitignore it if it holds real credentials).

• Claude config: one mcpServers entry per project/environment (myproject-javamelody, myproject-uat-javamelody, ...), each pointing at its own --config-file.

• A single config file can also list multiple microservices under one entry (see [[servers]] above) if they belong to the same project and should share one agent config entry — pick between them with the server tool argument.

Security notes

• Only GET ?format=json requests are made against JavaMelody's own monitoring endpoint — no write capability exists in this server.

• Never commit config files containing real basic-auth credentials.

• Use insecure = true only for self-signed certificates you trust (e.g. internal networks) — it disables TLS certificate verification for the whole process.