biome-mcp

A Model Context Protocol (MCP) server for running Biome on TypeScript and web projects with token-efficient output.

Overview

biome-mcp gives LLMs direct access to Biome's formatting, linting, and assist checks without shelling out to the CLI. Diagnostic output is parsed structurally and reduced to compact, grouped results before it reaches the model, so long check runs stay readable and cheap.

The server also caches the Biome CLI, configuration, and JavaScript linter documentation and exposes it as searchable resources.

Related MCP server: Code Search MCP

Features

• biome_check - Run formatting, linting, and assist checks in one pass

• biome_lint - Lint-only diagnostics with an all / error / warning severity filter

• biome_format - Verify formatting without modifying files

• Structured parsing - json-pretty output avoids fragile parsing of human-readable text

• Adaptive aggregation - large result sets include rule/file rollups before flat diagnostics

• changed_only - Check only staged, unstaged, and untracked web files (*.ts, *.tsx, *.js, ...)

• Documentation cache - Searchable, version-aware cache of Biome docs

• Bundled Agent Skill - Install biome-mcp skill into .agents/skills with one command

How It Works

biome-mcp implements the Model Context Protocol to expose Biome through read-only tools. Every check tool returns a CheckResult with compact output text and the underlying exit_code; it never writes to source files.

Usage

To start the server:

uvx biome-mcp

Or from a checkout:

uv run biome-mcp

Configure an MCP client to launch the server in the project directory to check, e.g. for opencode:

{
  "mcp": {
    "biome-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["biome-mcp"]
    }
  }
}

The server checks the project in its working directory. To target another directory, set BIOME_MCP_PROJECT_DIR.

Biome is invoked through bunx @biomejs/biome by default. Set BIOME_MCP_COMMAND_PREFIX to use another project-local invocation (see docs/configuration.md).

Agent Skill

Install the bundled biome skill in a project when the agent client discovers skills from .agents/skills:

uvx biome-mcp skill install biome --target .

The skill directs agents to the server's read-only tools and the cached documentation resources.

Configuration

Environment variables, all optional:

Documentation

See the docs for the full picture:

• Architecture - components, request flow, and output processing

• Configuration - environment variables and client setup

• Tools & resources - complete catalog with signatures

• Development - layout, tests, and contributing

Development

This project is built with FastMCP and uv.

uv sync --extra dev
uv run ruff check
uv run ruff format --check
uv run ty check
uv run pytest