[!注]

从Metals v1.6.6（锇）起，Metals 现在内置了一个独立的 MCP 服务器（[metals-mcp），可以通过 Coursier（cs install metals-mcp）安装。这使得 metals-standalone-client 项目变得不再必要。请使用官方的 metals-mcp 命令。

Metals 独立 MCP 客户端

一个独立客户端，支持MCP（模型上下文协议）的Metals语言服务器，使AI助手能够与Scala项目交互。采用scala-cli构建，实现快速编译和便捷分发。

目的

该工具提供了无头方式运行带有MCP功能的Metals语言服务器，使像Claude这样的AI代码助手能够理解并处理您的Scala代码库。它会自动发现Metals安装，配置语言服务器，并监控MCP服务器健康状况。

为什么需要这样做，它是如何运作的？

Metals 是一个 Scala 语言服务器，通常运行在编辑器（如 VS Code、Neovim 等）中。编辑器作为 LSP 客户端：启动 Metals，执行初始化握手，并发送配置。没有编辑器完成这些工作，Metals 无法启动。

[!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