Lighter MCP Toolkit

Read this first: live orders and withdrawals on Lighter are irreversible. Read DISCLAIMER.md before flipping mode = "live" or mode = "funds".

A portable Model Context Protocol server that exposes Lighter trading to any MCP-capable agent — Cursor, Claude Code, Claude Desktop, Codex, OpenClaw, and generic MCP clients — with safety as a first-class concern, not an afterthought.

The server wraps the official lighter-agent-kit Python scripts via subprocess and adds:

• Typed Pydantic input schemas with regex-validated symbols and

asset codes (no command-line argument injection).

• Mode-based safety gates (readonly → paper → live → funds):

the tool catalog grows monotonically; live and funds tools physically do not exist in the catalog until you opt in.

• Two-step confirmations for every fund-loss path: first call returns

a preview + single-use token, second call with the token executes. Tokens are bound to tool name + argument digest and TTL-limited.

• Atomic, UTC-keyed daily-notional ledger that fail-safes to

cap exhausted if its file is corrupt — never silently resets to 0.

• Append-only audit log with sanitized argv/result, intra-process

lock + POSIX flock, and soft-fail on disk errors.

• Streamable-HTTP transport that refuses to bind non-loopback hosts

unless --allow-remote is passed (the server has no built-in auth).

Why not just use the kit directly?

The kit is a CLI for a human. This server is the safety harness for a non-human caller. Every call is schema-validated, gate-checked, audited, and (for write paths) preview-confirmed before any subprocess runs against the exchange. The agent literally cannot reach the kit without going through these layers.

Quick start

One command, end to end:

pipx install lighter-mcp && lighter-mcp init

lighter-mcp init clones the upstream lighter-agent-kit into ~/.lighter/lighter-agent-kit, writes a default readonly config to ~/.lighter/lighter-mcp/config.toml, and auto-wires every MCP-capable agent it finds locally — Cursor, Claude Code, Claude Desktop, Codex — including slash-commands, the lighter-trader sub-agent, and the post-trade hook. Restart your agent and try:

/lighter-status

That's it. Live trading stays OFF until you flip it on in the config and re-run lighter-mcp doctor.

Other ways to install

<details> <summary><b>uvx (zero install, ephemeral)</b></summary>

uvx lighter-mcp init

uvx runs the published wheel from a cached venv. Good for one-off exploration; for steady-state use prefer pipx install so the agent config can point at a stable executable path.

</details>

<details> <summary><b>Docker (GHCR)</b></summary>

docker pull ghcr.io/iamgoatedaf/lighter-mcp:0.1.0
docker run --rm -it -v ~/.lighter:/data \
    ghcr.io/iamgoatedaf/lighter-mcp:0.1.0 \
    lighter-mcp init --no-scaffolds

The image ships with the kit pre-cloned at /opt/lighter-agent-kit and runs lighter-mcp serve on :8791 by default.

</details>

<details> <summary><b>From source (development)</b></summary>

git clone https://github.com/iamgoatedaf/lighter-mcp
cd lighter-mcp
python3 -m venv .venv && .venv/bin/pip install -e ".[dev,http]"
.venv/bin/lighter-mcp init

</details>

After any path above, lighter-mcp doctor should print a green health envelope.

Modes and tools

live and funds additionally require explicit [live] / [funds] config blocks with allowlists, notional caps, leverage caps, and confirmation flags. See docs/configuration.md.

Slash commands and sub-agent (Cursor / Claude Code / Codex)

The adapters ship a pre-built UI layer driven by the same MCP tools:

Plus a dedicated `lighter-trader` sub-agent with a narrow lighter_*-only tool budget that cannot edit source files and refuses to chain a kill without an explicit confirmation word.

The single source of truth for these prompts lives in adapters/_shared/. Per-platform folders are symlinks back into it.

Agent adapters

lighter-mcp init (no --agents) detects all installed agents at once. Per-platform READMEs explain exactly which UI surfaces exist for that agent and which require workarounds.

Examples

End-to-end walkthroughs in examples/:

• paper-demo.md — first paper trade,

step-by-step.

• guarded-live-order.md — full

two-step confirm flow on lighter_live_market_order.

• funding-scan.md — read-only scan of

funding rates across symbols.

• live-pnl-watcher/ — two-pane

terminal workflow: a WebSocket-driven PnL view that hot-reloads on paper-state.json changes, plus a trade.sh CLI wrapper for long/short/status while the watcher is running.

Hosted documentation site — website/ is a Mintlify project. Push to GitHub and Mintlify auto-deploys the site at https://lighter-mcp.mintlify.app (or your custom domain). Local preview: cd website && npm run dev.

Markdown deep-dives in docs/ (legacy / source material for the site):

• getting-started.md
• configuration.md — every key in the TOML.
• audit-log.md — record format, redaction rules,

retention strategy.

• security.md — companion to top-level

SECURITY.md.

Development

python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev,http]"
.venv/bin/ruff check .
.venv/bin/pytest -q   # 53 tests, fully hermetic by default

Tests that need a real lighter-agent-kit checkout are auto-skipped unless LIGHTER_KIT_PATH is set. See CONTRIBUTING.md for the contribution workflow and the bar for changes that touch safety.py, confirmations.py, or any lighter_live_* / lighter_funds_* tool.

Compatibility notes

• Tested against lighter-agent-kit as of April 2026. The wrapper relies

on the kit's query.py / trade.py / paper.py script entry points and their JSON stdout contracts — pin to a known-good kit commit if you fork.

• Python ≥ 3.10. Built and tested on macOS and Ubuntu; Windows works for

the server itself, but the per-platform adapters use symlinks — run adapters/_shared/sync.sh to materialize them as real files.

Project status

Alpha (`0.1.0`). Tool surface is stable enough to use, but expect schema-level breaking changes between minor versions until 1.0. See CHANGELOG.md.

License

MIT — see LICENSE.