Skip to content
MCP server

mcp-lint

Lint MCP tool schemas across eight clients and score how well agents recover from errors

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
1.0.4
Listing updated
2 days ago

About mcp-lint

mcp-lint is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

A schema can be valid JSON Schema and still break in one client or mislead an agent. mcp-lint runs shared rules plus client-specific ones for Claude, Cursor, Gemini, VS Code, Windsurf, Cline, OpenAI and Continue, and prints which tools survive in which client. Each cell in the compatibility matrix is marked measured or not observed, and a mark is not proof that a client accepts the schema.

Beyond linting, the CLI scores recorded failures to see whether an error tells the agent what to do next, and scores a proposed tool call against a policy file before it runs, returning allow, allow with rewrite, require approval or deny. Snapshots and diffs let CI fail when a later tool list adds an error. Reports can be written as terminal text, JSON, Markdown, SARIF 2.1.0 or a local HTML file.

A separate mcp-lint-server binary exposes rule listing, explain, check, fix, preflight and recovery scoring to an agent over stdio. The site is explicit about limits: Zed and OpenCode are not claimed, Windsurf and Cline config files are not scanned, and it does not call a tool to discover it.

Install

Run in a terminal

claude mcp add mcp-lint -- npx -y mcp-lint

Add to claude_desktop_config.json

{
  "mcpServers": {
    "mcp-lint": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-lint"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "mcp-lint": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-lint"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "mcp-lint": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-lint"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-lint": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-lint"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "mcp-lint": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-lint"
      ]
    }
  }
}

What it does

Eight-client rules
Checks schemas against Claude, Cursor, Gemini, VS Code, Windsurf, Cline, OpenAI and Continue.
Compatibility matrix
Shows which tools pass in which client.
Safe auto-fix
Writes only fixes classed safe; a dry run lists review and manual ones.
Recovery scoring
Scores whether a recorded failure tells the agent what to do next.
Preflight policy check
Scores a proposed call against a policy before it runs.
Snapshot and diff for CI
Fails a build when a new tool list adds an error.
Installed config scan
Lints servers configured in Cursor, Claude and VS Code.

Good for

  • Check a tools.json before publishing an MCP server
  • Find which clients reject a schema
  • Block schema regressions in CI
  • Review a proposed destructive call against a policy
  • Write a SARIF report for code scanning

Pricing

Open source

Prices change. Check mcp-lint-alpha.vercel.app before you buy.

mcp-lint FAQ

How do I run it?

Use npx mcp-lint@1.0.4, or install it globally or as a dev dependency with npm.

Does it call my tools?

Not to discover them. Recovery scoring calls a tool only when both --sandbox and --invoke are set.

Which report formats exist?

Terminal, JSON, Markdown, SARIF 2.1.0 and an HTML file that stays on your machine.

Which clients are not covered?

Zed and OpenCode are not claimed, and Windsurf and Cline config files are not scanned by --installed.

Is mcp-lint free?

Yes. mcp-lint is open source, so you can use and self-host it for free.

How do I add mcp-lint to Claude Code?

Run this command in your terminal: claude mcp add mcp-lint -- npx -y mcp-lint

What are the best alternatives to mcp-lint?

The closest alternatives to mcp-lint are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to mcp-lint

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools