linkwarden-mcp

Linkwarden용 Model Context Protocol 서버입니다. Linkwarden은 저장된 모든 페이지의 영구 복사본을 보관하는 자체 호스팅 북마크 관리자입니다.

MCP 클라이언트 — Claude Code, Claude Desktop, Codex — 가 북마크 컬렉션을 검색하고, 컬렉션과 태그로 정리하며, 저장된 페이지의 보존된 기사 텍스트를 읽을 수 있어, 아카이브된 링크를 다시 라이브 사이트를 가져오지 않고 요약하거나 인용할 수 있습니다.

📖 전체 문서는 linkwarden-mcp.ni-c.de에서 확인하세요

참고: Linkwarden의 공개 API 참조는 불완전합니다. 이 서버는 linkwarden/linkwarden의 apps/web/pages/api/v1/** 라우트와 packages/lib/schemaValidation.ts의 요청 스키마를 기준으로 작성되었으며, v2.16.0 (2026-08-17)에서 확인되었습니다. 이 두 파일이 여기에 있는 모든 도구의 진실 공급원(source of truth)입니다.

요구 사항

• Node.js ≥ 22

• 실행 중인 Linkwarden 인스턴스

• 설정 → 액세스 토큰에서 생성한 액세스 토큰

Linkwarden에는 토큰별 범위가 없습니다. 토큰은 생성한 계정의 모든 권한을 가집니다. 이 서버가 접근해야 하는 컬렉션에만 접근할 수 있는 전용 계정을 만들고, 관리자 토큰을 넘겨주지 마세요.

Related MCP server: linkwarden-mcp

구성

https://를 사용하세요. 일반 http를 사용하면 토큰이 암호화되지 않고 전송됩니다. 호스트가 로컬이 아닌 경우 서버에서 경고를 출력합니다. 자체 서명 인증서의 경우 LINKWARDEN_INSECURE_TLS보다는 적절한 내부 CA를 사용하는 것이 좋습니다.

토큰은 읽힌 후 프로세스 환경에서 제거되므로, 자식 프로세스나 /proc/<pid>/environ에서 볼 수 없습니다.

자격 증명 없이도 서버는 시작되고 도구 목록을 표시하므로, 레지스트리나 검사 도구가 내부를 들여다볼 수 있습니다. 그러나 모든 호출은 API에 도달하는 대신 설정 안내와 함께 실패합니다.

설치

Claude Code

claude mcp add linkwarden -e LINKWARDEN_URL=https://links.example.net -e LINKWARDEN_TOKEN=… -- npx -y linkwarden-mcp

Claude Desktop

{
  "mcpServers": {
    "linkwarden": {
      "command": "npx",
      "args": ["-y", "linkwarden-mcp"],
      "env": {
        "LINKWARDEN_URL": "https://links.example.net",
        "LINKWARDEN_TOKEN": "…"
      }
    }
  }
}

Codex

[mcp_servers.linkwarden]
command = "npx"
args = ["-y", "linkwarden-mcp"]
env = { LINKWARDEN_URL = "https://links.example.net", LINKWARDEN_TOKEN = "…" }

소스에서

npm install && npm run build
LINKWARDEN_URL=https://links.example.net LINKWARDEN_TOKEN=… node dist/index.js

Docker

docker build -t linkwarden-mcp .
docker run --rm -i \
  -e LINKWARDEN_URL=https://links.example.net \
  -e LINKWARDEN_TOKEN=… \
  linkwarden-mcp

도구

읽기

쓰기

LINKWARDEN_READ_ONLY=true인 경우 전혀 등록되지 않습니다. 🔒 표시된 도구는 확인 토큰이 필요합니다.

의도적으로 노출하지 않은 기능

• 액세스 토큰 관리 (/tokens). API 자격 증명을 생성할 수 있는 도구는 권한 상승 표면이 되며, 북마크 서버가 이를 보유할 이유가 없습니다.

• 사용자 관리 (/users, 계정 삭제). 범위를 벗어납니다.

• 백업 내보내기 및 가져오기 (/migration). 내보내기는 전체 인스턴스를 모델 컨텍스트에 덤프하고, 가져오기는 인스턴스를 파괴할 수 있습니다.

• 하이라이트. 생성하려면 보존된 문서의 정확한 문자 오프셋이 필요하지만, 모델이 의미 있게 생성할 수 없으며 Linkwarden은 기존 하이라이트를 나열하는 경로를 제공하지 않습니다.

• 아카이브 업로드 및 서명된 preserved URL. NEXT_PUBLIC_USER_CONTENT_DOMAIN이 구성되어 있어야 합니다.

• 더 이상 사용되지 않는 GET /links 목록 경로 — search_links는 대신 GET /search를 사용하며, Linkwarden 자체에서 권장하는 방식입니다.

안전

• 파괴적 도구는 두 단계로 이루어집니다. 첫 번째 호출은 정확한 대상에 바인딩된 수명이 짧은 확인 토큰을 반환하며, 두 번째 호출이 그 토큰을 가지고 있어야 작업이 수행됩니다. 모델은 이 게이트를 스스로 충족할 수 없으며, 한 링크, 태그 집합 또는 변경에 대해 발급된 토큰은 다른 용도로 재사용될 수 없습니다.

• 가시성 확대는 파괴적 행위로 간주됩니다. 컬렉션 공개 및 링크 URL 변경(이전 페이지의 모든 보존 복사본이 삭제됨)은 모두 확인이 필요하며, 단순 삭제만 해당되지 않습니다.

• 확인 프롬프트는 Linkwarden의 내용을 인용하지 않습니다. 제목, URL, 설명 및 컬렉션 이름은 저장된 페이지와 인스턴스의 다른 사용자로부터 비롯되며, 모델이 읽는 텍스트에는 숫자와 ID만 표시됩니다.

• 반환된 콘텐츠는 신뢰할 수 없는 데이터로 표시되며, 특히 보존된 기사 텍스트는 대상 사이트를 제어하는 사람이 작성한 것입니다.

• 부분 업데이트는 필드를 지우지 않습니다. Linkwarden의 업데이트 경로는 전체 레코드를 교체하므로, 이 서버는 현재 상태를 읽고 병합합니다. 그렇지 않으면 업데이트 시 링크의 태그나 컬렉션의 협력자가 조용히 사라집니다.

• 200 응답만으로 신뢰하지 않습니다. 여러 Linkwarden 경로는 HTTP 200과 본문에 오류 문장으로 실패를 보고하며, 사용된 메서드에 대한 핸들러가 없는 경로는 아무것도 없이 200으로 응답합니다. 이 두 경우 모두 성공적인 쓰기 대신 오류로 보고됩니다.

• 오류 본문은 잘리고, HTML 오류 페이지는 완전히 삭제되며, 리디렉션은 절대 따르지 않습니다(따라서 Bearer 토큰이 다른 호스트로 재사용될 수 없음). 모든 요청에는 타임아웃이 설정되어 있습니다.

• LINKWARDEN_READ_ONLY=true는 쓰기 도구를 전혀 등록하지 않습니다.

• 잔여 위험: 구성한 토큰의 권한 범위 내에서, 사용자가 확인한 후 모델이 파괴적인 작업을 수행하도록 요청받으면 실제로 수행될 수 있습니다. 계정의 범위를 좁히고, 호스트 수준의 권한 프롬프트를 유지하세요.

개발

npm install
npm run build
npm test
npm run test:coverage
npm run lint
npm run format
npm run docs:tools     # regenerate docs/reference/tools.md from the registered tools

docs/reference/tools.md는 생성되는 파일입니다. 커밋된 복사본이 더 이상 코드와 일치하지 않으면 CI가 실패합니다. 문서 사이트는 docs/에 있으며 자체 package.json과 lockfile을 가지고 있습니다. VitePress는 Docker 빌드 및 전체 테스트 매트릭스에서 실행되는 루트 설치에 포함되어서는 안 됩니다.

CONTRIBUTING.md를 참조하세요.

릴리스

모든 것은 태그로 구동됩니다. 수동 게시 단계는 없습니다.

1. CHANGELOG.md의 [Unreleased] 섹션을 새 버전으로 이동하고 날짜를 기입합니다. 릴리스 워크플로가 awk로 해당 섹션을 추출하므로 ## [x.y.z] 제목 형식이 중요합니다.

2. package.json의 version을 업데이트합니다.

3. npm run lint && npm run build && npm run test:coverage를 실행합니다.

4. 커밋한 후, 서명된 주석 태그를 만듭니다:

   git tag -s v0.1.1 -m "v0.1.1"
   git push origin main v0.1.1

그러면 release.yml이 태그가 package.json과 일치하는지 확인하고, Trusted Publishing(OIDC — 유출될 npm 토큰이 없음)을 통해 증명(provenance)과 함께 npm에 게시하며, 두 server.json 패키지 항목에 버전을 동기화하고, MCP 레지스트리에 게시한 후, 변경 로그 섹션에서 GitHub 릴리스를 생성합니다. ci.yml은 병렬로 멀티 아키텍처 컨테이너 이미지를 GHCR에 푸시합니다.

레지스트리 단계가 실패하면 main에서 수정하고 mcp-registry.yml 워크플로를 수동으로 실행하십시오. 실패한 작업을 다시 실행하는 것은 옵션이 아닙니다. 불변 태그를 체크아웃하므로 main의 수정 사항이 해당 태그에 도달할 수 없습니다.

라이선스

MIT © Willi Thiel