lazy-mcp

概览

A lazy proxy for MCP (Model Context Protocol) servers over stdio that defers starting the real server until a tool is actually called, serving discovery responses from a local cache in the meantime. Supports cache directory override via the LAZY_MCP_CACHE_DIR environment variable.

Why

When an agent connects to an MCP server, it immediately starts the server process and queries its capabilities (initialize, tools/list, resources/list, prompts/list). This happens for every configured server, even if none of their tools are ever used during the session.

For setups with many MCP servers this means:

  • Wasted resources — every server process runs for the entire session, consuming memory and CPU, even if never used.
  • Slow startup — the agent blocks while each server initializes. Servers that pull dependencies (e.g. uvx, npx) or connect to external services can take seconds each.
  • Unnecessary network traffic — servers that authenticate against APIs or fetch remote schemas do so eagerly, even when not needed.

lazy-mcp solves this by caching discovery responses and only starting the real server when a non-discovery request (like tools/call) arrives.

How it works

On the first run (no cache), lazy-mcp proxies transparently and builds the cache. On subsequent runs, discovery responses are served instantly from cache — the real server is never started unless a tool is actually called.

Installation

Shell

go install github.com/tkukushkin/lazy-mcp@latest

Or run without installing:

Shell

go run github.com/tkukushkin/lazy-mcp@latest -- uvx some-mcp-server

Or build from source:

Shell

git clone https://github.com/tkukushkin/lazy-mcp.git
cd lazy-mcp
go build -o lazy-mcp .

Usage

Wrap any MCP server command with lazy-mcp --:

// Claude Code config (~/.claude/claude_desktop_config.json)
{
  "mcpServers": {
    "some-server": {
      "command": "lazy-mcp",
      "args": ["--", "uvx", "some-mcp-server", "--arg1", "--arg2"]
    }
  }
}

Instead of:

{
  "mcpServers": {
    "some-server": {
      "command": "uvx",
      "args": ["some-mcp-server", "--arg1", "--arg2"]
    }
  }
}

Cache

Discovery responses are cached in the OS cache directory:

OS Path
macOS ~/Library/Caches/lazy-mcp/
Linux ~/.cache/lazy-mcp/

Each MCP server command gets its own cache file, keyed by a SHA-256 hash of the full command and arguments.

To clear the cache for all servers:

lazy-mcp clear-cache

The cache is updated every time the real server is started, so it stays fresh automatically.

Override cache directory

Set LAZY_MCP_CACHE_DIR to use a custom cache location:

Shell

LAZY_MCP_CACHE_DIR=/tmp/mcp-cache lazy-mcp -- uvx some-server

Zero dependencies

lazy-mcp is a single static binary with no external dependencies. It uses only the Go standard library.

License

MIT

相关 MCP Server

Context7 MCP - Up-to-date Code Docs For Any Prompt

A quality MCP server for Context7 that provides up-to-date, version-specific documentation and code examples for libraries directly into your prompt. Requires Node.js >= v18.0.0 runtime.

Playwright MCP

A Model Context Protocol (MCP) server that provides browser automation capabilities using Playwright. Enables LLMs to interact with web pages through structured accessibility snapshots without vision models. Requires Node.js 18 or newer.

@jshookmcp/jshook

MCP server with built-in tools across multiple domains for AI-assisted JavaScript analysis and security analysis — browser automation, CDP debugging, network monitoring, JS hooks, code analysis, and workflow orchestration.

Firecrawl MCP Server

MCP server for Firecrawl web scraping integration. Supports both cloud and self-hosted instances. Features include web scraping, batch processing, structured data extraction, and LLM-powered content analysis.

Luma MCP

Multi-model vision understanding MCP server providing unified image analysis capabilities for AI assistants without native vision support. Requires API keys for model providers configured via environment variables.

Chrome DevTools MCP

MCP server for Chrome DevTools that lets your coding agent control and inspect a live Chrome browser for automation, debugging, and performance analysis. Requires Node.js 22+ and a current stable Chrome browser.