Lint JavaScript/TypeScript files with ESLint rules via @eslint/mcp (npx) — official ESLint MCP server

Recipe: Lint JS files via @eslint/mcp over stdio

Package: @eslint/mcp v0.3.7 (official ESLint project) Transport: stdio Entry point: node node_modules/@eslint/mcp/src/mcp-cli.js (NOT dist/ — the dist directory doesn't contain the server files despite package.json suggesting it) Tools exposed: 1 — lint-files Auth: none required

Setup

npm install --prefix /tmp/eslint-mcp @eslint/mcp

The server uses the cwd to locate eslint.config.js (flat config, ESM). Create a project directory with your config:

// eslint.config.js
export default [
  {
    rules: {
      "no-unused-vars": "warn",
      "eqeqeq": "error",
      "no-var": "warn",
      "prefer-const": "warn",
      "no-console": "warn"
    }
  }
];

MCP Client Connection

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["/tmp/eslint-mcp/node_modules/@eslint/mcp/src/mcp-cli.js"],
  cwd: "/tmp/eslint-test"
});
const client = new Client({ name: "pathfinder", version: "1.0" });
await client.connect(transport);

Tool Schema

lint-files({ filePaths: string[] }) — returns per-file results with filePath, errorCount, warningCount, messages[] where each message has ruleId, severity (1=warn, 2=error), line, column, message, messageId, optional fix (byte-range {range:[start,end], text}), and optional suggestions[].

Gotchas

1. Entry point is `src/mcp-cli.js`, NOT `dist/` — the dist directory doesn't have the server files.
2. cwd determines config — the server resolves eslint.config.js from the spawned process's cwd, not from the file being linted.
3. TypeScript files need explicit config — without @typescript-eslint/eslint-plugin configured, .ts files return "File ignored because no matching configuration was supplied."
4. Response text includes model instructions — the response content includes "you must display the full list to the user" and "ask the user for confirmation before attempting to fix" — these are meant for the LLM consuming the output.
5. First call ~25ms (ESLint init), subsequent 1-6ms — JIT warmup on first invocation.
6. Empty filePaths array is rejected — validation error, must pass at least one path.
7. Nonexistent files — returns isError: true with "No files matching the pattern were found."
8. Clean files — return 0 errors/0 warnings with empty messages array (not an error).

Verified trace (9 calls, 100% success)

1. Lint file with multiple issues — lint-files({filePaths:["/tmp/eslint-test/test.js"]}) — returned 8 messages: 3 no-var warnings, 1 eqeqeq error (with suggestion offering ===), 1 no-unused-vars warning, 2 no-console warnings, 1 prefer-const warning. Fix objects included byte ranges for auto-fix.
2. Clean file — lint-files({filePaths:["/tmp/eslint-test/clean.js"]}) — 0 errors, 0 warnings.
3. Multi-file — lint-files({filePaths:["/tmp/eslint-test/test.js","/tmp/eslint-test/clean.js"]}) — returned results array with both files, dirty file had issues, clean file had none.
4. Nonexistent file — lint-files({filePaths:["/tmp/eslint-test/nope.js"]}) — isError: true, "No files matching the pattern were found."
5. TypeScript file — lint-files({filePaths:["/tmp/eslint-test/test.ts"]}) — "File ignored because no matching configuration was supplied" (needs TS config).
6. Empty array — lint-files({filePaths:[]}) — validation error.

7-9. Repeated calls — consistent sub-6ms response times after warmup.