Files

T

test0r abd9db30f2 Add Bearer auth, rewrite example server, add README

- lmcp.lua: optional Bearer token auth via conf file or explicit token
- lmcp.lua: CORS Authorization header allowed
- example_server.lua: rewritten with non-blocking shell, file ops, search
- README.md: usage, auth config, Claude Code integration, tool examples

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-11 19:15:27 +02:00

2.6 KiB

Raw Blame History

lmcp — Lightweight MCP Server in Lua

A minimal Model Context Protocol server in pure Lua. ~350 lines, 2.4MB RSS, zero compiled dependencies beyond Lua + LuaSocket.

Features

MCP 2025-03-26 protocol (JSON-RPC over HTTP)
Tool registration with JSON Schema validation
Optional Bearer token authentication (config file or explicit)
SSE and plain JSON response modes
Non-blocking shell execution with timeout
Runs on any Linux with Lua 5.4 + LuaSocket

Quick Start

# Install dependencies (Debian/Ubuntu)
apt install lua5.4 lua-socket

# Or use a self-contained archive (see releases)
tar xzf lmcp-linux-amd64.tar.gz
export PATH=$PWD/lmcp-linux-amd64/bin:$PATH

# Run
lua5.4 example_server.lua
# lmcp: my-tools v0.1.0 listening on 0.0.0.0:8080/mcp

Files

File	Description
`lmcp.lua`	Core library — HTTP server, JSON-RPC, MCP protocol, auth
`json.lua`	Minimal JSON encoder/decoder (bundled, no external dep)
`example_server.lua`	Example server with shell, read/write file, list/search tools

Authentication

To require a Bearer token, create an lmcp.conf next to your server:

.godparticle = your-secret-token-here

Then reference it when creating the server:

local server = lmcp.new("my-tools", {
    port = 8080,
    conf = dir .. "lmcp.conf",
})

Clients must send Authorization: Bearer <token> on every request. OPTIONS (CORS preflight) is exempt.

You can also set the token directly:

local server = lmcp.new("my-tools", {
    auth_token = "my-secret-token",
})

Claude Code Integration

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "my-host": {
      "type": "url",
      "url": "http://my-host:8080/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Adding Tools

server:tool("greet", "Say hello to someone.", {
    type = "object",
    properties = {
        name = { type = "string", description = "Who to greet" },
    },
    required = { "name" },
}, function(args)
    return "Hello, " .. args.name .. "!"
end)

Tool handlers return a string (wrapped as text content) or a table (encoded as JSON). Errors thrown via error() are caught and returned as MCP error responses.

Self-Contained Archives

Pre-built archives with Lua 5.4 + LuaSocket for Linux:

lmcp-linux-amd64.tar.gz — x86_64
lmcp-linux-aarch64.tar.gz — ARM64 (Pi 5, RK3588, etc.)

These include the Lua interpreter and LuaSocket shared library so no system packages are needed.

License

MIT

2.6 KiB Raw Blame History