[!NOTE]

As of Metals v1.6.6 (Osmium), Metals now includes a built-in standalone MCP server (metals-mcp) that can be installed via Coursier (cs install metals-mcp). This makes the metals-standalone-client project unnecessary. Please use the official metals-mcp command instead.

Metals Standalone MCP Client

A standalone client that launches the Metals language server with MCP (Model Context Protocol) support, enabling AI assistants to interact with Scala projects. Built with scala-cli for fast compilation and easy distribution.

Purpose

This tool provides a headless way to run Metals language server with MCP capabilities, allowing AI code assistants like Claude to understand and work with your Scala codebase. It automatically discovers Metals installations, configures the language server, and monitors MCP server health.

Why is this needed and how does it work?

Metals is a Scala language server that normally runs inside an editor (VS Code, Neovim, etc.). The editor acts as an LSP client: it launches Metals, performs the initialization handshake, and sends configuration. Without an editor doing this work, Metals doesn’t start.

This standalone client replaces the editor. It acts as a headless LSP client so that Metals can run without any editor open. Here’s what happens when you run it:

1. The standalone client discovers and launches Metals as a subprocess (via Coursier).
2. It performs the LSP handshake over stdin/stdout (initialize, initialized) using JSON-RPC 2.0.
3. It configures Metals to enable its built-in MCP server by sending startMcpServer: true.
4. Metals starts the MCP server and writes a .mcp.json file at your project root with the connection URL:

   {
     "mcpServers": {
       "metals": {
         "url": "http://localhost:/mcp",
         "type": "http"
       }
     }
   }
   

5. The standalone client monitors the MCP server health via HTTP polling to make sure it stays up.

Once this is running, you can open Claude Code (or another MCP-aware AI assistant) in your Scala project directory.

This gives AI assistants access to Scala language intelligence (go-to-definition, find-references, completions, diagnostics, etc.) without requiring an IDE.

For a detailed diagram and component breakdown, see ARCHITECTURE.md.

Quick Start

Download Pre-built Executables

Linux:

wget https://github.com/jpablo/metals-standalone-client/releases/latest/download/metals-standalone-client-linux-executable
chmod +x metals-standalone-client-linux-executable
./metals-standalone-client-linux-executable --help

macOS:

wget https://github.com/jpablo/metals-standalone-client/releases/latest/download/metals-standalone-client-macos-executable
chmod +x metals-standalone-client-macos-executable
./metals-standalone-client-macos-executable --help