LocalRecall MCP Server

A Model Context Protocol (MCP) server for LocalRecall knowledge base management.

• Multiple Modes: Supports stdio, HTTP, and SSE transport modes
• Knowledge Management: Full CRUD operations for LocalRecall collections and documents
• Search Capabilities: Semantic search across your knowledge base
• Flexible Configuration: Command-line flags, environment variables, or configuration files
• Collection Isolation: Lock the server to a single collection for security
• Multiple Output Formats: JSON, YAML output formats
• Cross-platform: Native binaries for Linux, macOS, and Windows

git clone https://github.com/futuretea/localrecall-mcp-server.git
cd localrecall-mcp-server
make build

docker build -t localrecall-mcp-server .

./localrecall-mcp-server \
  --localrecall-url http://localhost:8080 \
  --localrecall-collection my-collection

./localrecall-mcp-server \
  --port 8080 \
  --localrecall-url http://localhost:8080 \
  --localrecall-api-key your-api-key

Configuration can be set via CLI flags, environment variables, or a config file.

1. Command-line flags
2. Environment variables (prefix: LOCALRECALL_MCP_)
3. Configuration file
4. Default values

./localrecall-mcp-server --help

Create config.yaml:

port: 0  # 0 for stdio, or set a port like 8080 for HTTP/SSE

log_level: 5

localrecall_url: http://localhost:8080
localrecall_api_key: your-api-key
localrecall_collection: my-collection  # locks server to this collection

list_output: json

enabled_tools: []
disabled_tools: []

Use LOCALRECALL_MCP_ prefix with underscores:

LOCALRECALL_MCP_PORT=8080
LOCALRECALL_MCP_LOCALRECALL_URL=http://localhost:8080
LOCALRECALL_MCP_LOCALRECALL_API_KEY=your-api-key

claude mcp add localrecall -- /path/to/localrecall-mcp-server \
  --localrecall-url http://localhost:8080 \
  --localrecall-collection my-collection

Add to .vscode/mcp.json or ~/.cursor/mcp.json:

{
  "servers": {
    "localrecall": {
      "command": "/path/to/localrecall-mcp-server",
      "args": [
        "--localrecall-url",
        "http://localhost:8080",
        "--localrecall-collection",
        "my-collection"
      ]
    }
  }
}

Search content in a LocalRecall collection.

Parameters:

• query (string, required): The search query
• max_results (number, optional): Maximum number of results (default: 5)
• collection_name (string, required*): The collection to search

Add a document to a LocalRecall collection.

Parameters:

• filename (string, required): The filename for the document
• file_path (string, optional): Path to file to upload
• file_content (string, optional): File content as string
• collection_name (string, required*): The collection to add to

Create a new collection in LocalRecall. Hidden when collection isolation is active.

Parameters:

• name (string, required): The name of the collection to create

Reset (clear) a collection in LocalRecall. Hidden when collection isolation is active.

Parameters:

• name (string, required): The name of the collection to reset

List all collections in LocalRecall. Hidden when collection isolation is active.

Parameters: None

List files in a LocalRecall collection.

Parameters:

• collection_name (string, required*): The collection to list

Delete an entry from a LocalRecall collection.

Parameters:

• entry (string, required): The filename of the entry to delete
• collection_name (string, required*): The collection to delete from

* When --localrecall-collection is set, collection_name is removed from all tool schemas and automatically enforced. The parameter is only required in multi-collection mode.

When running with a port number, the server exposes these endpoints:

• /healthz - Health check
• /mcp - Streamable HTTP endpoint
• /sse - Server-Sent Events endpoint
• /message - Message endpoint for SSE clients

Example:

./localrecall-mcp-server --port 8080 \
  --localrecall-url http://localhost:8080 \
  --localrecall-api-key your-api-key

Access at: http://localhost:8080

make build

make test

make format

npx @modelcontextprotocol/inspector@latest $(pwd)/localrecall-mcp-server \
  --localrecall-url http://localhost:8080

localrecall-mcp-server/
├── cmd/                        # Application entry points
├── internal/cmd/               # Command-line interface
├── pkg/
│   ├── client/                 # LocalRecall API client
│   ├── core/                   # Core utilities (config, logging, version)
│   ├── server/                 # MCP and HTTP servers
│   └── toolset/                # Tool implementations

Apache-2.0

Contributions are welcome! Please feel free to submit a Pull Request.

• GitHub Issues: https://github.com/futuretea/localrecall-mcp-server/issues
• LocalRecall Documentation: https://github.com/mudler/LocalRecall