Skip to main content
Glama

luaLLM-MCP

MCP Server for luaLLM - safe model management via leases.

Installation

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the MCP server
make install

Related MCP server: MCP Server with Local LLM

Configuration

Runtime state is stored in OS-appropriate application data directories:

  • Linux/macOS: ~/.config/luaLLM-MCP/

  • Windows: %LOCALAPPDATA%\luaLLM-MCP\

Override with:

export LUALLM_MCP_STATE_DIR=/custom/path
export LUALLM_MCP_LEASE_TTL_SECONDS=7200  # 2 hours (default)

Usage

# Run the MCP server
make run

# Or directly with uv
uv run python mcp_server.py

The server uses stdio transport for MCP communication. It will print startup info and then wait for requests from an MCP client.

Manual Testing

Test that the server initializes correctly:

uv run python -c "
import asyncio
from mcp import StdioServerParameters
from mcp.client.stdio import stdio_client
from mcp import ClientSession

async def test():
    params = StdioServerParameters(command='uv', args=['run', 'python', 'mcp_server.py'])
    async with stdio_client(params) as (read_stream, write_stream):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()
            tools = await session.list_tools()
            print(f'Found {len(tools.tools)} tools:')
            for t in tools.tools:
                print(f'  - {t.name}')

asyncio.run(test())
"

Expected output:

Found 9 tools:
  - list_models
  - get_model_info
  - get_server_status
  - get_capabilities
  - acquire_model
  - release_model
  - get_model_logs
  - health_check
  - list_leases

MCP Tools

Tool

Description

list_models()

List all available models

get_model_info(model_name)

Get model metadata

get_server_status()

Get running servers

get_capabilities()

List MCP capabilities

acquire_model(model_name, preset?, client_id?, purpose?)

Acquire lease on model

release_model(lease_id)

Release lease

get_model_logs(instance_id, lines=100)

Get model logs

health_check()

Check luaLLM availability

list_leases()

List current leases

Safety Features

  • Allowlist only: Only approved tools exposed

  • Lease-based lifecycle: Models only stopped when all leases released

  • Instance isolation: Different presets = different instances

  • Atomic state writes: State file updated safely

  • Structured errors: All responses are JSON with success/error fields

Development

make check   # Verify imports work
make test    # Run tests
make clean   # Clean build artifacts

Architecture

Lease Model

Models are "leased" when started via MCP. Workflows acquire leases via acquire_model() and release them with release_model(lease_id). A model is only stopped when the last lease is released.

State Schema

{
  "schema_version": "1.0",
  "instances": [
    {
      "instance_id": "uuid",
      "model": "mistral-7b",
      "preset": "throughput",
      "managed_by_mcp": true,
      "started_at": "2024-01-01T10:00:00Z",
      "port": 8080
    }
  ],
  "leases": [
    {
      "lease_id": "uuid",
      "instance_id": "uuid",
      "client_id": "claude-3-5-sonnet",
      "purpose": "chat-completion",
      "acquired_at": "2024-01-01T10:01:00Z",
      "renewed_at": "2024-01-01T10:30:00Z"
    }
  ]
}

Instance Matching

acquire_model() only reuses an existing instance when both model and preset match exactly. Different presets create different instances.

A
license - permissive license
-
quality - not tested
C
maintenance

Maintenance

Maintainers
Response time
Release cycle
Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ripter/luaLLM-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server