lucidlink-mcp 0.2.1

Model Context Protocol server for LucidLink filespaces

LucidLink MCP Server (beta)

Connect AI agents (Claude Code, Codex, Cursor, and other MCP clients) to a LucidLink filespace - read, write, search, lock, manage users and audit files in natural language.

Prerequisites

• A LucidLink service-account token (sa_live:...) for a filespace you can safely test in. Your LucidLink workspace admin can mint one - see Service Accounts.
• Node.js 22+ on PATH - only for the admin tools (workspace, members, permissions). The file tools do not need Node.

You don't need Python set up in advance; uv brings its own.

Install

The client configs below launch the server with uvx, so the only thing to install is uv (it brings its own Python, no separate setup):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
irm https://astral.sh/uv/install.ps1 | iex

Reload your PATH so uvx is found: open a new terminal (on macOS/Linux you can instead source $HOME/.local/bin/env in the current shell). If uv warns about PATH later, run uv tool update-shell. uvx lucidlink-mcp@latest fetches the package on first run and picks up new releases automatically on later launches, so there's no separate install or update step. Check it works:

uvx lucidlink-mcp@latest --version

Prefer a bare lucidlink-mcp command (to pin a version, or to keep uvx out of your config)? Install it with uv tool install lucidlink-mcp, or pip install lucidlink-mcp into a Python 3.10+ environment. Then use lucidlink-mcp wherever the configs below say uvx lucidlink-mcp@latest, and update it yourself with uv tool upgrade lucidlink-mcp (or pip install -U); a bare install doesn't auto-update.

Configure your token

uvx --from lucidlink-mcp@latest lucidlink-mcp-setup

Prompts for the token, validates it, and stores it in ~/.lucidlink/mcp-config.json (mode 0600), so no client config has to carry it. (Installed the bare command? Just run lucidlink-mcp-setup. Prefer not to use the setup tool at all? See Fallbacks below.)

That's the whole setup. If your account sees several filespaces, the agent lists them on first use and you tell it which to link, or pin a default with LUCIDLINK_FILESPACE (see Settings).

Register with your client

Claude Code - via the CLI:

claude mcp add lucidlink -s user -- uvx lucidlink-mcp@latest

...or in .mcp.json at the project root (shareable; Claude Code asks to approve it once):

{
  "mcpServers": {
    "lucidlink": {
      "command": "uvx",
      "args": ["lucidlink-mcp@latest"]
    }
  }
}

Add options as env vars - -e LUCIDLINK_MCP_TOOLSETS=admin (CLI) or an "env" object (JSON); see Settings below for the full list.

Codex - via the CLI:

codex mcp add lucidlink -- uvx lucidlink-mcp@latest

...or in ~/.codex/config.toml:

[mcp_servers.lucidlink]
command = "uvx"
args = ["lucidlink-mcp@latest"]

Add options as env vars - --env LUCIDLINK_MCP_TOOLSETS=admin (CLI) or a [mcp_servers.lucidlink.env] table (TOML); see Settings below. The token comes from ~/.lucidlink/mcp-config.json (via lucidlink-mcp-setup), so no LUCIDLINK_TOKEN is needed here.

Cursor - ~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json (per-project):

{
  "mcpServers": {
    "lucidlink": {
      "command": "uvx",
      "args": ["lucidlink-mcp@latest"]
    }
  }
}

Add an "env" object for options, e.g. "env": { "LUCIDLINK_MCP_TOOLSETS": "admin" }. If Cursor can't find uvx, give its absolute path (command -v uvx).

Settings

All optional except the token. Put them in the env block of your client's server entry.

Variable	Effect
LUCIDLINK_TOKEN	the token (or set it once via lucidlink-mcp-setup and omit this)
LUCIDLINK_FILESPACE	default filespace to link when several are visible
LUCIDLINK_ACCOUNT	default account name when several accounts are configured (see below)
LUCIDLINK_MCP_TOOLSETS	admin adds workspace-management tools; core trims to 16 essential file tools
LUCIDLINK_MCP_READ_ONLY	1 registers only read/search tools; nothing can write
LUCIDLINK_MCP_NODE	absolute path to a Node 22+ binary, if the admin tools can't find node

Agents can link SEVERAL filespaces at once (linking is additive; switching back is instant). To work across several service accounts, put named tokens in ~/.lucidlink/mcp-config.json instead of a single token:

{
  "accounts": { "prod": "sa_live:...", "staging": "sa_live:..." },
  "defaultAccount": "prod"
}

The agent just names a filespace: link_filespace resolves it across accounts and switches automatically (use_account(name) exists for switching identity explicitly). A lone token is simply the single account named default, so existing setups keep working unchanged.

Try it

Ask your agent:

• "List my LucidLink filespaces", then "show me the files in /"
• "Create /beta-test/hello.txt with a short note, then read it back"
• "Search the filespace for files named hello.txt" (finds the file you just made)

Connect an S3 data store (optional)

Link existing S3 objects into the filespace (read-only). S3 keys never reach the agent - put them in ~/.lucidlink/data-stores.json (mode 0600), keyed by store name:

{ "my-store": { "access_key": "AKIA...", "secret_key": "...",
                "bucket_name": "my-bucket", "region": "us-east-1" } }

Then ask the agent to register the store (register_data_store) and link an object (link_external_file). Needs a filespace at V9+ with Connect enabled; see the project README for the rest.

Enabling the audit trail (optional)

The agent can answer who changed which files, and when once the filespace's audit trail is on. It's off by default, and enabling it needs filespace-admin rights:

• On a machine with the desktop client connected, a filespace admin runs lucid config --global --set --Audit.FsEvents 1 (details).

---

Fallbacks & troubleshooting

Set the token without the setup tool - two equivalents:

• Write ~/.lucidlink/mcp-config.json yourself as { "token": "sa_live:..." } and chmod 600 it.
• Or put "env": { "LUCIDLINK_TOKEN": "sa_live:..." } in your client's server entry.

Several service accounts? Run lucidlink-mcp-setup --account NAME once per account, or hand-author the accounts object (see Settings); re-runs preserve existing named accounts either way.

Command not found, or client shows "disconnected"? The launcher (uvx, or lucidlink-mcp if you installed the bare command) isn't on the PATH your client sees, common with GUI clients that start from a minimal PATH. Put its absolute path in the config; command -v uvx (or command -v lucidlink-mcp) prints it. As a last resort, run the server module directly: python3 -m lucidlink_mcp.

License and usage

This MCP server (the “MCP Server”) is proprietary to LucidLink Corp. and is provided solely to enable you to install, run, and self-host the MCP Server, and to develop applications and integrations that interact with LucidLink services.

Use of this MCP Server is governed by the LucidLink Terms and Conditions available at: https://www.lucidlink.com/terms (the “LucidLink Terms”), or, if you or your organization have entered into a separate written agreement with LucidLink governing your use of LucidLink services (for example, a subscription agreement or master services agreement), such separate written agreement.

This MCP Server (including any associated example or sample code) is not licensed under an open‑source license. All rights are reserved by LucidLink except as expressly granted in the Applicable Terms.