remnawave-mcp

Remnawave 패널 API를 위한 MCP 서버입니다.

@folexz 스코프로 게시됩니다. npm의 스코프 없는 remnawave-mcp 이름은 Remnawave 2.7.4를 대상으로 하는 무관한 프로젝트에 속하며 2.8.0 이상에서는 동작하지 않습니다.

npx -y @folexz/remnawave-mcp   # configured via REMNAWAVE_BASE_URL + REMNAWAVE_API_TOKEN_READ/_WRITE

28개 컨롤러에 걸친 205개 전체 작업을 다룹니다. Remnawave API v3.3.2 — 사용자, 노드, 호스트트, 구성 프로파일, 스쿼드, 구독, 노드 플러그인, 인프라 청구, 시스템 통계 — 을 모두 패널의 자체 OpenAPI 문서에서 생성한 것입니니다 수기로 작선한 것이 아니다. 더 새로운 스펙를 입려면 npm run build-spec를 실행하세면 플면이 함께 상신됩니다.

주요 특징

• 스펙 기반이며 스스로 업데어트된다 npm run update-spec은 Remnawave가 공개한 최신 OpenAPI 문서를 가져와 카탈로그를 다시 빌니다. 모든 작업의 입력 스키마는 작업의 파라미터와 요청 본문에서 그대ид로 나 은니다. API에 대해 수기된 내용이 하나도 없게 있고, 다시 빌드하면 추가되거나 제거되거나 이름이 바뀐 모든 작업을 보여주는 diff가 출력됩니다. 따라서 버전 상승이 조용히 도구를 누락시킬 수 없습니다.

• 제한된 컨텍스트 비용. 205개 타입된 도구는 매 요청마다 tools/list로 약 39k 토큰을소모합니다. 기본 프로파일은 5개 도구(약 1.4k 토큰)만 노출하면서도 모든 작업에 접근할 수 있습니다 — 왜 205개 도구가 아닌가를 참조하세요.

• 2개 토큰으로 최소 권한 인증. 읽기 토큰과 선택적 쓰기 토큰. GET은 읽기 토큰을 사용하고, POST/PATCH/PUT/DELETE는 쓰기 토큰을 사용합니다. 쓰기 토큰이 없으면 변경 작업 도구는 아예 등록되지 않으며, 서버는 물리적으로 읽기 전용입니다.

• 실사용 패널을 위한 안전장치. 구성 쓰기가 발생할 때마다 패널이 모옸 노드에 설정을 밀어넣고 Xray를 재시작하기 때문에, 변경 작업은 최소 간격으로 직렬화되고 보요쫄 체라 백오프로 재시도됩니다. 벌크 및 삭제 작업은 추가로 confirm: true가 필요합니다.

• 필드 노트가 포함된다. 아래의 주의사항은 해당 작업에 첨부되어 도구 설명과 remnawave_describe_operation 출력에 나타납니다.

• 실패할 수 없는 요청. 16개 엔드포인트(ъ auth, passkeys, api 토큰 관리)는 로그인؛ 한 관리자 JWT에만 서비스되며 API 토큰은 거부 합니다. 이들은 스펙에서 감지되어 원격으로 보 네이지 않고 설명과 함체 로컬에서 거부됩니다.

• 탈출구. REWNA_WAVE_REQUEST_READ / REWNAWAVE_REQUEST_WRITE는 문서화되지 않은 라우트와 OpenAPI가 표현할 수 없는 쿼리 구문 을 포함한 어떤 경로에도 접근할 수 있습니다.

요구 사항

• Node.js ≥ 18

• HTTPS로 접근 가능한 Remnawave 패널(3.x)

• 패널 데몬에서 발급한 API 토큰: Settings → API t 기가필요합니다. Remnawave로 3.x는 스코프된 토큰을 지원하오, 읽기 스코프가 있는 하나와 변경을 원한다면 쓰기 스코프가 있는 두 번째 것을 발급받으세요.

설치

빠른 경로는 npx — Claude Code 등록을 참조하세요. 소스에서 실행하려면:

git clone https://github.com/folexz/remnawave-mcp.git
cd remnawave-mcp
npm install
npm run build

설정

모든 설정은 MCP의 호스트가 입력하는 환경 변수를 통해서 받습니다. 읽는 파일이 없습니다.

Claude Code에 등록

읽기 전용(권장 기본값):

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  -- npx -y @folexz/remnawave-mcp@latest

변경 작업을 활성화하고 일상적인 컨트롤러에 type 도구를 쓰려면:

claude mcp add remnawave --scope user \
  --env REMNAWAVE_BASE_URL=https://panel.example.com \
  --env REMNAWAVE_API_TOKEN_READ=your_read_token \
  --env REMNAWAVE_API_TOKEN_WRITE=your_write_token \
  --env REMNAWAVE_TOOL_PROFILE=core \
  -- npx -y @folexz/remnawave-mcp@latest

@latest를 사용하면 npx가 각 실행 시 최신 발행 버전을 확인합니다. 로컬 빌드를 사용하려면 명령어를 node /absolute/path/to/remnawave-mcp/dist/index.js로 변경하세요.

Claude Desktop 또는 다른 MCP 클라이언트에 등록

{
  "mcpServers": {
    "remnawave": {
      "command": "npx",
      "args": ["-y", "@folexz/remnawave-mcp@latest"],
      "env": {
        "REMNAWAVE_BASE_URL": "https://panel.example.com",
        "REMNAWAVE_API_TOKEN_READ": "your_read_token"
      }
    }
  }
}

왜 205개 도구가 아닌가

tools/list는 매 요청마다 모델에 다시 보내지므로, 직렬화된 크기는 고정적인 컨텍스트 세금입니다. 이 스펙에서 측정한 수치(npx tsx scripts/tool-stats.ts):

Remnawave의 DTO는 full이 이렇게 비교험한 이유입니다. 하나의 역직렬화된 호스트 객체만 해도 JSON Schema가 약 30 KB이며, 모든 사내 및 보안 변형을 내장하고 있기 때문입니다.

따라서 서버는 "작업당 하나의 도구"와 "단순한 디스패처" 중 하나를 고르지 않고, 두 가지를 모두 제공하며 프로파일이 얼마나 많은 것을 노출할지를 결정하게 합니다.

1. 카탈로그 도구 (항상 켜짐, 3개). REMWAVE_LIST_OPERATIONS은 카탈로그를 탐색/검색하여 각 작업을 한 단의 한 줄로 반환하고, remnawave_describe_operation은 작업 하나의 전체 JSON Schema와 필드 노트를 반환하며, remnawave_call은 이름으로 205개 중 하나를 실행합니다. 일반적인 흐름은 목록 → 설명 → 호출리스트 → describe → call이며, API가 아무리 커져도 동일하게 1.4k 토큰 비용입니다. 이는 에이전트 프레임워크가 도구 스키마를 지연 로드할 때 사용하는 것과 같은 편법입니다.

2. 타입된 도구 (프로파일 선택). 실제 사용하는 컨트롤러에 대해 각 작업 하나의 생성된 도구입니다. core는 사용자, 노드, 호스트, 구성 프로파일, 내부 스쿼드, 시스템및 두 개의 벌크 작업 컨트롤러를 포함하고, full은 모든 것을 포함하며 minimal은 없습니다. REMNAWAVE_MAX_SCHEMA_BYTES보다 큰 스키마는 최상위 필드는 유지하고 중첩을 제거한 뒤 전체 버전은 remnawave_describe_operation으로 안내해둡니다.

3. 탈출구 (2개). 스펙이 빠뜨린 모든 것을 위한원시 GET과 원시 쓰기입니다.

모든 경로는 같은 실행자를 통하기 때문에, 쓰기 게이트, 파괴적 확인 게이트, 경로 템플릿, 쿼리 처리 모두 어느 인터페이스를 쓰든 동일하게 동작합니다.

프로파일은 취향껏 수정합니다. MCP 서버가 여러 개 있으면 minimal, 일들 작업을 원터치로 하고 싶으면 core, 컨텍스트가 넉넉하면 full.

필드 노트 — 스펙에 없는 동작

이 모든 것은 실제 3.3.2 패널에서 검증hard이며, 도구 설명에서 영향을 받는 작업에 첨부되어 있습니다.

• PATCH /api/config-profiles는 패치가 아니라 교체입니다. 본문은 {uuid, config}이며 config는 반드시 완전하고 유효한 Xray 구성이어 합니다. 일부 조각을 보내면 A061: Config doesn't have inbounds 오류가 납니다. 올바른 순서는 GET /api/config-profiles/{uuid} → 반환된 config 객체를 그자리에서 수 → → PATCH로 전체를 보내는입니다.

• 패널은 127.0.0.1:3000에 응답하지 않습니다. 패널 호스트 자체에서도 마찬가지고, docker-proxy가 수신 대가 있더라도 그렇습니다(curl은 exit 52빈응답을 반환). 항상 공개 HTTPS origin을 사용하고 Bearer 토큰을 붙이세요.

• **모든 응답은 {"response": ...}로 싸여 있습니다.**이 서버는 이 것을 풀어서 툴출력이 페이로드 건Cop নিজেই 됩니다.

• 호스트는 중첨된 inbound.configProfileUuid를 통해 프로파일에 바인딩됩니다 — 최상위 configProfileUuid가 아닙니다. (그리고 inbound.configProfileletteUuid). 실제 호스트로 확인했습니다: 중첨은 있고, 최상위는 없습니다.

• PATCH를 연달아 실행하면 패널은 죽습니다. 쓰기 요청을 구성할 때마다 모든 노드에 설정을 밀어내고 거기서 Xray를 재시작하며, 연속으로 몇 개가 발동하면 패널 자체의 TLS 리스너가 응답하지 않게 됩니다.

• POST /api/subscription-templates is only for a blank template; content is uploaded by separate PATCH /api/subscription-templates; JSON and YAML bodies cannot be updated in the same call.

• 호스트의 serverDescription에 대한 텍스트는 30자까지만 허용하며 (스펙의 maxLength으로 확인됨) 이를 이용해 Hysteria2 호스트가 Happ에서 raw JSON이 아닌 적절하게 보이게 할 수 있습니다.

• 본 Soleure. Exin 방금건 이 서버가 방교환 태그: " 관리자-JWT-only 요청 contains..." This fragment should not be translated. Place verbatim.

• Sixteen endpoints are JWT-only — auth와 passkeys의 전체 컨트롤러에 API 토큰 관리(GET/POST /api/tokens, DELETE /api/tokens/{uuid}, GET /api/tokens/scopes)입니다. 패널은 API 토큰에게 401/403으로 응답합니다. 이 서버는 스펙에서 이들을 감지해 로컬에서 거부합니다; REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1로 설정하면 실제 관리자 JWT인 경우에만 게이트를 해제합니다.

• GET /api/users/stream은 단일 문서 대신 줄바꿈 구분 JSON으로 응답합니다. 텍스트 블롭으로 전달하지 않고 사용자 레코드 배열로 파싱됩니다.

• PATCH /api/hosts 는 실제 부분 패치 입니다. {uuid, serverDescription}만으로도 잘 동작합니다. 전체를 교체하는 의미론을 갖는 것은 프로필입니다. 실제로 확인했습니다.

• 오류는 {message, errorCode}로 돌아오며, errorCode(예: A061)는 이 서버의 오류 텍스트에 포함됩니다.

도구 범위

모든 컨트롤러는reboutrage_call와 탈출구를 통해 도달할 수 있습니다. typed 컬럼은 커밋된 각 컨트롤러가 표시하는 것을 표시합니다.

실제 서버에서 remnawave_list_operations를 실행하면 정확하고 최신인 작업 집합을 얻을 수 있습니다.

예시

타입 없는 도구로 탐색하고 호출하기:

// 1. What is there?
{ "tool": "remnawave_list_operations", "arguments": { "controller": "nodes" } }

// 2. What does it take?
{ "tool": "remnawave_describe_operation",
  "arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart" } }

// 3. Do it.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_post_nodes_uuid_actions_restart",
                 "params": { "uuid": "…" } } }

구성 프로필을 안전하게 편집하기(A061 함정):

// Read the whole profile first — PATCH replaces the config wholesale.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_get_config_profiles_uuid", "params": { "uuid": "…" } } }

// Send the full, edited config back.
{ "tool": "remnawave_call",
  "arguments": { "operation": "remnawave_patch_config_profiles",
                 "params": { "body": { "uuid": "…", "config": { /* complete Xray config */ } } } } }

스펙으로는 표현할 수 없는 쿼리 구문:

{ "tool": "remnawave_request_read",
  "arguments": { "path": "/api/users",
                 "query": { "size": 25, "start": 0,
                            "filters[0][id]": "status", "filters[0][value]": "ACTIVE" } } }

테스트

npm run build
npm test            # 50 unit tests + the offline smoke suite
npm run test:unit   # unit tests alone

단위 테스트는 조용히 실패하는 부분들을 다룹니다: Remnawave의 재귀적 DTO를 통한 $ref 확장, 도구 이름 도출(길이 예산, 결정성, 충돌 감지), 카탈로그 diff, 두 개의 쓰기 게이트, admin-JWT 게이트, 스키마 축소 및 NDJSON 파싱.

실제 패널에 대한 읽기 전용 검사

패널에 접근할 수 있고 환경에 읽기 전용 토큰이 있으면, 스모크 스크립트는 실시간 읽기 전용 호출(변경 호출은 절대 아님)도 실행합니다:

REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$REMNAWAVE_API_TOKEN" \
npm run smoke

토큰이 이미 있는 곳(예: 패널 호스트)에서 실행하면 비밀이 유출되지 않습니다. 스크립트는 형태(타입, 키 이름, 배열 길이)만 출력하고 실제 값은 절대 출력하지 않으므로, 그 출력물은 이슈에 붙여 넣어도 안전합니다.

가드레일 검사는 의도적으로 http://127.0.0.1:9를 가리키므로, 게이트가 열린 채 실패하더라도 실제 패널에 도달할 수 없습니다.

쓰기 경로 검증

읽기만으로는 토큰 라우팅, 스로틀, 확인 게이트 및 부분 패치의 의미가 실제로 동작하는지 증명할 수 없습니다. scripts/write-check.mjs는 아무도 붙들고 있지 않은 객체들로 이를 증명하고, 건드리는 기존 객체 하나는 원래 상태로 되돌려 놓습니다:

REMNAWAVE_BASE_URL=https://panel.example.com \
REMNAWAVE_API_TOKEN_READ="$T" REMNAWAVE_API_TOKEN_WRITE="$T" \
node scripts/write-check.mjs --i-understand-this-mutates [--host-uuid <uuid>]

이 스크립트는 인바운드와 멤버가 없는 내부 스쿼드를 생성했다가 다시 삭제하고, 또 호스트의 serverDescription을 다시 쓴 다음 원래 값으로 복원합니다. 승인 플래그가 없으면 시작을 거부하며, 무엇인가 남아 있으면 0이 아닌 종료 코드를 반환합니다.

실제 3.3.2 패널에서 확인된 내용: 실제 DELETE에서 확인 게이트가 유지됩니다. 부분 PATCH /api/hosts가 동작합니다. 패널은 31자의 serverDescription을 거부합니다. 원래 값(null 포함)이 왕복으로 보존됩니다. 연속 변경은 설정된 1500ms 하한 간격을 준수하여 각각 1525ms, 1524ms 간격으로 실행되었습니다.

로컬에서 검사하기

REMNAWAVE_BASE_URL=https://panel.example.com REMNAWAVE_API_TOKEN_READ=xxx npm run inspect

API 스펙 업데이트

API에 관한 모든 것은 하나의 파일에서 비롯되므로, 최신 Remnawave 릴리스를 추적하는 것은 명령어 하나입니다:

npm run update-spec            # fetch the newest spec + rebuild the catalogue
npm run update-spec -- --strict  # additionally fail if any operation disappeared or was renamed
npm run build && npm test      # compile and verify

스펙의 출처

https://cdn.remna.st/docs/openapi.json — Remnawave 자체의 Build&Push OpenAPI Specs 워크플로가 모든 업스트림 태그에서 게시하므로 항상 최신 릴리스를 설명합니다. --url <u> 또는 REMNAWAVE_SPEC_URL로 재정의해 다른 출처를 고정할 수 있습니다.

패널 인스턴스는 사용 가능한 출처가 아닙니다: 문서는 배포에서 활성화하지 않는 한 비활성화되어 있고, 활성화하더라도 일반적인 리버스 프록시가 라우팅하지 않는 /backend-tools/swagger에 Swagger가 마운트됩니다. 실제 3.3.2 패널을 직접 확인한 결과 모든 일반적인 스펙 경로에서 404가 반환됩니다.

다운로드는 파싱 결과가 paths가 비어 있지 않은 OpenAPI 문서일 때만 디스크에 기록되므로, 오류 페이지나 관별 포털이 정상 스펙을 덮으면 수 없습니다.

이후 확인할 내용

build-spec은 새 카탈로그를 이전 카탈로그와 diff하여 모든 변경 사항을 출력합니다:

build-spec: Remnawave API v3.4.0 -> 211 operations, 28 controllers, 315 KB
  methods: DELETE=22 GET=90 PATCH=19 POST=78 PUT=2  admin-JWT-only: 16
  diff: API version 3.3.2 -> 3.4.0
  REMOVED — tools that will disappear (1):
    remnawave_get_old_thing  (GET /api/old-thing)
  added (7):
    ...

• REMOVED / RENAMED 사항은 해당 도구를 이름으로 참조하는 프롬프트나스크립트가 있는 모근에서 호한(breaking이) 됩니다. --strict는 이 항목들을 0이 아닌 종료 코드로 바꾸며, 자동화에서 사용해야 하는 플래그입니다.

• added는 안전합니다. 새 작업은 remnawave_call을 통해 즉시 호출할 수 있고, 해당 컨트롤러가 활성 프로필에 있으면 타입 지정된 도구도 제공받습니다.

• schema changed는 실제 사용 중인 작업에서 한 번 살펴볼 가치가 있습니다.

npm test는 그다음 디스크에 있는 카탈로그가 새 빌드와 일치하는지, 모든 도구 이름이 고유하고 64자 예산 안에 있는지, 그리고 가드 레일이 여전히 유지되는지를 다시 확인합니다.

자동화

npm run update-spec -- --strict   # exits non-zero on a breaking catalogue change
npm test
npm version minor --no-git-tag-version
git commit -am "chore: Remnawave API 3.4.0" && git push
git tag "v$(node -p "require('./package.json').version")" && git push --tags

푸시된 태그가 릴리스 워크플로를 실행해 npm에 다시 게시합니다. @folexz/remnawave-mcp@latest로 등록된 클라이언트는 다음 시작 시 새 버전을 가져갑니다.

릴리스하기 (유지관리자)

첫 게시 — 반드시 수동

npm은 아직 존재하지 않는 패키지에 대해 신뢰성 게시자(trusted publisher)를구성할 수 없습니다. 해당 설정은 패키지 자체의 설정 페이지에 있습니다. 이는 알려진 미해결 제한사항(npm/cli#8544)이며, scoped 패키지에도 동일하게 적용됩니다. 따라서 0.1.0 버전은 로그인한 머신에서 올려야 합니다:

npm whoami            # must print the account that owns the @folexz scope
npm publish --access public

--access public은 필수입니다: scoped 패키지는 기본적으로 restricted로 설정되기 때문입니다.

그다음 토큰 없는 릴리스로 전환

패키지가 존재하면, npm 전환: npmjs.com에서 @folexz/remnawave-mcp → Settings → Trusted Publisher로 이동하여 저장소 folexz/remnawave-mcp와 워크플로 release.yml로 GitHub Actions 발행자를 추가합니다. package.json에 있는 repository.url은 GitHub 저장소와 정확히 일치해야 합니다 — 당연히 일치합니다.

그 후에는 .github/workflows/release.yml이 OIDC를 통해 푸시된 모든 vX.Y.Z 태그를 게시합니다 — 토큰 없음, 비밀 없음, 출처 증명(provenance) 자동 연결 상태로:

npm version patch --no-git-tag-version
git commit -am "chore: v0.1.1"
git push
git tag v0.1.1 && git push origin v0.1.1

워크플로는 lockfile을 다시 설치하고, 재빌드하고, 대중적으로 단위 테스트와 오프라인 스모크 스위트를 실행하며, 태그가 package.json과 통합되지 않으면 즉시 실패합니다.

@folexz/remnawave-mcp@latest로 등록된 클라이언트는 다음에 실행될 때 새 버전을 가져갑니다.

보안 주의사항

• 토큰은 환경변수에서만 읽으며 절대로 기록하지 않습니다. 로그는 stderr로 내보내고, stdout은 MCP JSON-RPC 채널입니다.

• REMNAWAVE_API_TOKEN_READ만 지정하는 것을 권장합니다. 쓰기 토큰 없이는 변경 도구 자체가 존재하지 않으므로, 손상되었거나 오류적인 클라이언트도 패널을 변경할 수 없습니다.

• 구독 엔드포인트는 정공 클라이없트 구성을 반환합니다. 해당 출력을 비밀로 취급하세요.

• 실제 토큰을 커밋하지 마세요. .env가 gitignore에 있으며, .env.example은 그 형식을 보여 줍니다.

알려진 제한 사항

• 본문 검증은 패널에 위임됩니다. 이 서버는 필수 인자가 존재하는지만 확인합니다. 즉 필수 body가 있는지만 확인하며, 본문 내부의 형태를 스키마 검사하지는 않습니다. 이는 의도적입니다 — 패널이 이미 모든 필드를 검증하고 정확한 message + errorCode(A061 등)로 응답하며, 그 검증을 로컬에 중복 구현하면 JSON Schema 검증기와 잠재적으로 어긋난 규칙 복사본을 배포하게 되기 때문입니다. 대가로, 형태가 잘못된 본문은 한 번의 왕복 후에 오류가 발생합니다.

• 가능한 경우에는 사전 정의된 게이트를 우회합니다. remnawave_request_write은 설계상 원시(raw) 요청입니다. 여전히 쓰기 토큰을 요구하며 스로틀과 재시도 로직은 거치지만, 확인할 작업이 없기 때문에 파괴적인 confirm 게이트 또는 admin-JWS는 적용하지 않했. 스펙에 없는 경로가 필요가 없는 한 remnawave_call을 우선 사용하세요.

• 도구는 제공되는 스펙(v3.3.2) 수준으로만 최신입니다. 다른 마이너 버전의 패널은 그 보다 더 많은 라아트를 노출할 수도 있습니다. 그것이바로 탈출구(escape hatch)를 위한 것입니다. API 스펙 업데이트를 확인하세요.

• admin-JWT 엔드포인트는 차단되지만 구현되지 않습니다. 이 서버는 API 토큰만 보관하고, admin 로그인, 세션 유지, JWT 갱신을 수행하지 않습니다. admin JWT를 토큰으로 공급하고 REMNAWAVE_ALLOW_ADMIN_JWT_OPS=1을 설정하면 '16'개 엔드포인트를 호출할 수 있지만, 만료와 재발급은 직접 감당해야 합니다.

• Prometheus 기본 인증 정보 엔드포인트는 이 스펙에 이름만 없고 노출되지 않습니다.

• write-check.mjs는 패치합니다. 패널리저 전용 도구로, npm test에서 제외되고 제거와 승인 플랫 포함되지 않conceivably 두려우며 실행을 거부합니다.

라이선스

MIT — LICENSE 참조.