Metadata-Version: 2.4
Name: lucidlink-mcp
Version: 1.0.0
Summary: Model Context Protocol server for LucidLink filespaces
Author: LucidLink
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://www.lucidlink.com
Project-URL: Documentation, https://developer.lucidlink.com/docs/mcp/overview
Project-URL: Release notes, https://github.com/LucidLink/lucidlink-mcp
Keywords: mcp,lucidlink,llm,ai,agent,filesystem
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: lucidlink==1.0.0
Requires-Dist: mcp==2.0.0
Requires-Dist: watchdog==6.0.0
Requires-Dist: typing_extensions==4.15.0
Requires-Dist: certifi>=2026.10.19
Dynamic: license-file

# LucidLink MCP Server

<!-- mcp-name: com.lucidlink/mcp -->

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](https://support.lucidlink.com/hc/en-us/articles/40222074543757-Getting-Started-with-Service-Accounts-API-Authentication).
- 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](https://docs.astral.sh/uv/) (it brings its own Python, no
separate setup):

```bash
# 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:

```bash
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.11+ 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

```bash
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](#fallbacks--troubleshooting) 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](#settings)).

## Register with your client

**Claude Code** - via the CLI:

```bash
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):

```json
{
  "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](#settings) below for the full list.

**Codex** - via the CLI:

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

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

```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](#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):

```json
{
  "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). Each linked filespace allocates a 1 GiB disk cache that stays until the
server exits, and an account holds at most 4 links at once (`maxLinkedFilespaces`
in `~/.lucidlink/mcp-config.json`). To work across several service accounts, put
named tokens in `~/.lucidlink/mcp-config.json` instead of a single token:

```json
{
  "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 accounts
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 /mcp-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)

## Link S3 objects and URLs (optional)

LucidLink Connect links existing content into the filespace without copying it;
the agent reads it like any file, read-only. It needs filespace format 3.6 or
newer with Connect enabled.

**S3 objects** come through an S3 data store. Its keys never reach the agent -
put them in `~/.lucidlink/data-stores.json` (mode 0600), keyed by store name:

```json
{ "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`, kind `s3`) and
link an object (`link_external_file`).

**HTTP/HTTPS URLs** link with `link_external_url`. On filespace format 3.8 and
newer a URL link belongs to an HTTP-link data store, which needs no credentials
(`register_data_store`, kind `http_link`); on 3.6 it links without one.

## 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](https://support.lucidlink.com/hc/en-us/articles/31125255979533-Audit-Trail-with-New-LucidLink)).

---

## 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](#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`.

## Telemetry

The MCP server sends usage telemetry to LucidLink: one event per tool call and one per workspace connection. An event records the tool name, its outcome and duration, the kind of error if it failed, the filespace, service-account and workspace ids it concerns, the MCP client's name and version, the server and SDK versions, the operating system and its version, the CPU architecture, the Python version, whether the read-only toolset is on, and ids that correlate the events of one run. It never carries paths, filenames, tool arguments or file content. The `lucidlink` SDK the server runs on sends its own usage telemetry, described in its README on PyPI. LucidLink collects this data under the Developer Platform License Agreement (see "License and usage") and handles personal data under its privacy policy: https://www.lucidlink.com/privacy.

## License and usage

This MCP server (the “MCP Server”) is proprietary to LucidLink Corp. and is part of the LucidLink Developer Platform. It 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 Developer Platform License Agreement, available at https://developer.lucidlink.com/LucidLink%20Developer%20Platform%20License%20Agreement.pdf (the “Agreement”), or, if you or your organization have entered into a separate written agreement with LucidLink that governs your use of the Developer Platform, by that separate written agreement (in each case, the “Applicable Terms”). See the `LICENSE` file for details.

The MCP Server runs on the LucidLink Python SDK (the `lucidlink` package on PyPI), which it uses unmodified under the same Agreement; the SDK's own license notice ships with that package.

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. Third-party components bundled with the MCP Server are licensed under their own terms; see the `NOTICE` file.
