Docs · MCP

MCP server setup.

Beta

The Ledgerful MCP stdio server exposes 10 tools to AI assistants that support the Model Context Protocol.

Package status

The MCP server ships as part of the Ledgerful CLI. The standalone @ledgerful/mcp-server package is published on npm.

npm package published: @ledgerful/mcp-server is published on the public npm registry at version 0.1.10. It downloads the prebuilt binary from the v0.1.8 GitHub release. npx and npm install instructions are actionable.

Start the server with:
npx @ledgerful/mcp-server

Start the MCP server

Run ledgerful mcp from inside the repository root you want to analyze. The server reads layout.root from the current working directory — there is no --root flag.

# From inside your target repository root:
ledgerful mcp

Working directory matters: The MCP server auto-detects the project root from layout.root in the current working directory. Your MCP client must launch the server from the repository root, not from your home directory or a parent directory. The cwd field in the client configuration is how you control this.

Client configuration

Configure your AI client to start the Ledgerful MCP server as a stdio process. The cwd field must point to your repository root.

Example configuration for Claude Desktop or a compatible MCP client:

{
  "mcpServers": {
    "ledgerful": {
      "command": "ledgerful",
      "args": ["mcp"],
      "cwd": "/path/to/your/repo"
    }
  }
}

Replace /path/to/your/repo with the absolute path to the repository root you want to analyze. On Windows use a backslash path such as C:\Users\you\projects\myrepo.

Available tools

The server exposes 10 tools. All tools operate over local data — no source code is uploaded.

Tool	Description
`scan`	Run a risk scan on changed files and return structured impact data.
`search`	Full-text search over the local ledger and index.
`ask`	Ask a natural-language question about the repository and receive a grounded answer.
`ledger_status`	Return the current ledger commit count, last committed hash, and signing status.
`ledger_search`	Search the signed ledger for provenance records matching a query.
`hotspots`	Identify high-churn files and risky change concentrations in the repository.
`endpoints_changed`	List API endpoint surfaces that changed in the current diff.
`security_boundaries`	Report trust boundaries and data-flow edges that the current diff crosses.
`dead_code`	Identify symbols in the diff that may be unreachable or unused.
`verify_plan`	Verify a proposed change plan against ledger provenance and risk data.

← Dashboard GitHub Action →