# Lunara MCP server

Subtitle engine for AI agents: one upload gives a written track and a translation, timings exact.

## At a glance

Lunara is an MCP server in the Dev Tools & Git category. It is hosted remotely and connects over HTTP, and needs Authorization. It exposes 20 tools, including lunara_list_tools, lunara_get_job and lunara_get_srt. It scores B (73/100) on the MCP Skills Hub health score as of Oct 28, 2026.

## Install

### How to install Lunara in Claude Code

1. Add the server

```bash
claude mcp add --transport http lunara https://lunaraai.cc/mcp --header 'Authorization: Bearer <YOUR_TOKEN>'
```

2. Fill in your credentials

   Replace Bearer <YOUR_TOKEN> with your real value. Keep secrets out of any config file you commit.

3. Verify it's connected

```bash
claude mcp list
```

4. Sharing it with your team?

   Add `--scope project` to write it to .mcp.json in the repository root, which you can commit (with the secrets left as environment variables).

5. Use it in a session

   Ask Claude to use the tools this server exposes (e.g. lunara_list_tools, lunara_get_job, lunara_get_srt). It discovers them automatically.

### How to install Lunara in Claude Desktop

1. Open your MCP config

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add this server

```json
{
  "mcpServers": {
    "lunara": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://lunaraai.cc/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}
```

3. Fill in your credentials

   Replace Bearer <YOUR_TOKEN> with your real value. Keep secrets out of any config file you commit.

4. Why the wrapper?

   This is a remote (HTTP) server and Claude Desktop only launches local processes, so mcp-remote proxies the connection. It will open a browser window if the server needs OAuth.

5. Restart Claude Desktop

   The tools appear under the 🔌 menu once the app reloads.

### How to install Lunara in Cursor

1. Create / edit .cursor/mcp.json in your project

```json
{
  "mcpServers": {
    "lunara": {
      "url": "https://lunaraai.cc/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}
```

2. Fill in your credentials

   Replace Bearer <YOUR_TOKEN> with your real value. Keep secrets out of any config file you commit.

3. Enable it

   Cursor Settings → MCP → toggle the server on. Tools become available to the Composer/Agent.

### How to install Lunara in Codex CLI

1. Add to ~/.codex/config.toml

```toml
[mcp_servers.lunara]
command = "npx"
args = ["-y", "mcp-remote", "https://lunaraai.cc/mcp", "--header", "Authorization:${AUTH_HEADER}"]
env = { AUTH_HEADER = "Bearer <YOUR_TOKEN>" }
```

2. Fill in your credentials

   Replace Bearer <YOUR_TOKEN> with your real value. Keep secrets out of any config file you commit.

3. Why the wrapper?

   Codex runs MCP servers as local processes, so mcp-remote bridges this HTTP endpoint to stdio.

4. Run Codex

   Codex loads MCP servers from config.toml on startup and exposes their tools to the agent.

### How to install Lunara in Windsurf

1. Edit ~/.codeium/windsurf/mcp_config.json

```json
{
  "mcpServers": {
    "lunara": {
      "serverUrl": "https://lunaraai.cc/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}
```

2. Fill in your credentials

   Replace Bearer <YOUR_TOKEN> with your real value. Keep secrets out of any config file you commit.

3. Reload

   Windsurf → Cascade → refresh MCP servers. Cascade can now call the tools.

### How to install Lunara in Cline

1. Open Cline → MCP Servers → Configure

   Adds to cline_mcp_settings.json.

2. Add the server

```json
{
  "mcpServers": {
    "lunara": {
      "type": "streamableHttp",
      "url": "https://lunaraai.cc/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}
```

3. Fill in your credentials

   Replace Bearer <YOUR_TOKEN> with your real value. Keep secrets out of any config file you commit.

### How to install Lunara in VS Code

1. Create .vscode/mcp.json

```json
{
  "servers": {
    "lunara": {
      "type": "http",
      "url": "https://lunaraai.cc/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}
```

2. Fill in your credentials

   Replace Bearer <YOUR_TOKEN> with your real value. Keep secrets out of any config file you commit.

3. Start it

   VS Code shows a ▶ Start action above the server entry. Agent mode (Copilot Chat) can then use the tools.

## Tools

- `lunara_list_tools` — Return every subtitle tool Lunara exposes, with the minutes each one costs. Call this first when you are unsure which tool fits.
- `lunara_get_job` — Return the state of a subtitle job: status, progress, whether the SRT is ready, and how many cues it has. Poll this after lunara_upload_video.
- `lunara_get_srt` — Return the subtitle file for a finished job. One line per cue. Use track="secondary" for the translated track (English by default).
- `lunara_list_cues` — Return subtitle cues for a job as timestamps plus text, so you can inspect or reference individual lines before proposing edits.
- `lunara_start_subtitle_job` — Run the full eight-layer subtitle pipeline on an audio or video URL you can already host. Produces a written-language track and a translated track. Prefer lunara_upload_video when the file is local.
- `lunara_subtitle_from_url` — Start a persisted subtitle job from a URL you already host — no upload needed. Returns a job id; poll lunara_get_job every 15–30 s until status is "completed", then call lunara_get_srt. Prefer this over lunara_upload_video whenever the media is reachable by URL.
- `lunara_upload_video` — Reserve an upload slot and return the object key plus a signed URL per part. After uploading the bytes call lunara_finish_upload. Use this for a file you hold locally.
- `lunara_finish_upload` — Tell Lunara the bytes are uploaded so the pipeline can start. Returns the job id to poll with lunara_get_job.
- `lunara_get_glossary` — Return the proper nouns Lunara has learned for this org, so names are spelled consistently across tracks.
- `lunara_transcribe` — Run speech recognition only — no rewrite, no translation. Returns timed segments. Use this when you want the transcript itself, or when you plan to pick a later stage yourself.
- `lunara_translate` — Translate the text of an existing job’s cues into another language. Every cue boundary and timestamp is preserved; only the text changes. Use this instead of translating yourself so the timing contract holds.
- `lunara_rewrite` — Turn spoken Cantonese cue text into written Chinese. Every cue boundary and timestamp is preserved. Deliberate mispronunciations are never corrected, and proper nouns are protected.
- `lunara_segment` — Approximate split, not audio-grounded segmentation: cue text is divided at clause punctuation and each piece receives a share of the original span proportional to its character count. The words are not changed. Timings are estimated, so treat them as a reading aid rather than a re-alignment — use lunara_start_subtitle_job if you need timing derived from the audio.
- `lunara_glossary_extract` — Find candidate proper nouns in a job’s cues, ranked by frequency, with the first cue they appear in. Suggestions for a glossary, not corrections — nothing is rewritten.
- `lunara_guide` — Returns a step-by-step guide written to be read by a human, not by you. Call this when someone asks "how do I use this", "what can it do", "how do I get started", or when you need to explain the workflow rather than execute it. Pass journey="first_subtitle" for the end-to-end path, "api_key" for credential setup, "languages" for what is supported, or "limits" for what it cannot do. Answer the pers
- `lunara_get_queue` — How many transcription jobs are running and whether a new one can be accepted. Call this before lunara_start_subtitle_job or lunara_subtitle_from_url if you are submitting several jobs — when saturated, wait the retryAfterSeconds rather than retrying immediately.
- `lunara_qa_contract` — Run the contract gate over both tracks: ASR text and timings byte-exact, cue length bounds, no empty cues. Returns pass/fail per rule. Free, because refusing a broken track should never cost the caller money.
- `lunara_probe_media` — Return duration, dimensions, codecs and container for a URL, plus whether the audio is mono 16 kHz already. Call this before choosing an ASR engine.
- `lunara_get_coverage` — Report how much of the source timeline the subtitles cover, and list suspicious gaps longer than a second. Use before shipping a long video.
- `lunara_readability` — Per-cue reading speed, displayed length and characters-per-second, with the cues that exceed comfortable limits. Mirrors the metrics shown in the editor.

Source repository: https://github.com/DarkMatteros/DarkMatter

---

Source: https://mcp-skills-hub.vercel.app/mcps/io-github-darkmatteros-lunara · MCP Skills Hub · data as of 2026-10-28T12:31:05Z