MCP Server

개요

Web2MD MCP server는 AI 어시스턴트가 직접 호출할 수 있는 도구 세트로 Web2MD를 노출합니다. 이는 AI 모델을 외부 도구 및 데이터 소스에 연결하기 위한 개방형 표준인 Model Context Protocol (MCP)를 사용합니다. 설정을 완료하면 Claude, Cursor, Windsurf에게 페이지 변환, Library 검색 및 동기화, Chrome extension을 통한 일괄 변환, 저장된 Skill 불러오기 등을 대화에서 벗어나지 않고 요청할 수 있습니다.

MCP server를 사용하려면 Web2MD API 키(PRO 플랜)가 필요합니다. 대시보드에서 키를 생성하거나, npx web2md-cli login을 실행해 한 번 인증하면 CLI와 키를 자동으로 공유할 수 있습니다(아래 인증 참고).

사용 가능한 도구

MCP server는 기능별로 그룹화된 11개의 도구를 제공합니다.

도구	설명
`convert_url`	서버 측 변환기를 통해 모든 URL을 깔끔한 Markdown으로 변환
`bridge_convert_url`	Chrome extension을 통해 HTTP로 URL을 변환 — Reddit, JS 렌더링, 로그인 보호 페이지용
`agent_convert`	Native messaging을 통해 Chrome extension으로 URL을 변환(`bridge_convert_url`과 사용 사례는 동일하나 전송 방식이 다름)
`agent_batch_convert`	Native messaging을 통해 Chrome extension으로 최대 50개 URL을 일괄 변환
`search_library`	키워드 및/또는 태그로 저장된 Library를 검색
`get_library_items`	id로 Library 항목의 전체 Markdown을 가져옴
`sync_library`	Library를 로컬 디렉터리에 Markdown 파일로 동기화
`list_skills`	Web2MD 클라우드 계정에 저장된 Skill 목록 조회
`get_skill`	id 또는 이름으로 하나의 Skill 전체 내용을 가져옴
`semantic_search`	지원 종료(Deprecated) — 대신 `search_library` + `get_library_items` 사용
`get_conversion`	지원 종료(Deprecated) — 대신 `search_library` + `get_library_items` 사용

convert_url

URL을 서버 측에서 가져와 제목, 단어 수, 예상 읽기 시간과 함께 페이지 콘텐츠를 Markdown으로 반환합니다. REST API와 동일한 변환 옵션(includeImages, includeLinks)을 지원합니다. 예시 프롬프트: “이 URL을 markdown으로 변환해줘: https://docs.example.com/getting-started”

bridge_convert_url

실행 중인 Chrome extension을 통해(로컬 HTTP bridge로) URL의 HTML을 가져온 뒤, 서버 측에서 그 HTML을 Markdown으로 변환합니다. 서버가 직접 접근할 수 없는 페이지 — Reddit, 로그인이 필요한 사이트, JS 렌더링이 심한 페이지 — 에 사용하세요. Web2MD extension이 설치된 Chrome이 열려 있어야 하며, extension ID는 API 키로부터 자동 탐지됩니다. 예시 프롬프트: “bridge를 사용해서 이 Reddit 스레드를 변환해줘: https://reddit.com/r/…“

agent_convert

bridge_convert_url과 동일하게 Chrome extension을 통해 URL을 변환하지만, HTTP 대신 Agent Bridge native-messaging 채널을 사용합니다. 선택적 skill 파라미터를 지원합니다. Skill id 또는 이름을 전달하면 그 내용이 반환된 Markdown에 추가되어 에이전트가 즉시 활용할 수 있습니다. Extension과 native host가 설치된 Chrome이 실행 중이어야 합니다. 예시 프롬프트: “이 페이지를 summarize skill을 적용해서 변환해줘: https://…“

agent_batch_convert

agent_convert와 같은 전송 방식을 사용하지만, 최대 50개의 URL 배열을 받아 한 번의 호출로 순차 변환합니다. 여러 개의 Reddit 스레드나 JS 렌더링 페이지를 한 번에 가져올 때 가장 적합합니다. 예시 프롬프트: “이 12개 URL을 Markdown으로 일괄 변환해줘: […]“

search_library

저장한 모든 페이지를 담은 Web2MD Library를 키워드(제목 및 전체 페이지 콘텐츠와 매칭)와/또는 태그로 검색하며, 최신순으로 정렬됩니다. 전체 Markdown이 아니라 간결한 메타데이터(id, 제목, url, 날짜, 태그)를 반환합니다. Free 플랜 계정은 결과에서 최근 항목만 볼 수 있으며, 결과가 잘렸을 경우 도구가 이를 알려줍니다. 예시 프롬프트: “인증 관련 내용을 내 library에서 검색해줘”

get_library_items

id로 Library 항목의 전체 Markdown 콘텐츠를 가져옵니다(호출당 최대 20개 — 먼저 search_library로 id를 찾으세요). 응답이 클 수 있으므로, 긴 페이지의 경우 호출당 5개 이하의 id로 나눠서 요청하세요. 예시 프롬프트: “library 항목 abc123과 def456의 전체 콘텐츠를 가져와줘”

sync_library

전체 Library를 태그별로 정리되고 frontmatter가 포함된 Markdown 파일로 로컬 디렉터리에 동기화합니다. 기본적으로 증분 방식이며(<dir>/.web2md-sync.json에 커서를 추적), 전체를 다시 스캔하려면 full: true를 전달하세요. 이는 CLI에서 web2md sync가 실행하는 것과 동일한 동기화입니다 — 워크플로우에 맞는 방식을 사용하세요. 예시 프롬프트: “내 library를 ~/notes/web2md에 동기화해줘, ‘research’ 태그만”

list_skills

Web2MD 클라우드 계정에 저장된 Skill을 간결한 배열(id, 이름, 설명)로 나열합니다. 전체 내용을 가져오려면 get_skill을 사용하세요. 예시 프롬프트: “내가 저장한 skill이 뭐가 있지?“

get_skill

id 또는 이름으로 하나의 Skill의 SKILL.md 형식 전체 내용 — 지침, 설명, 콘텐츠 전체 — 를 가져옵니다. id를 모른다면 먼저 list_skills를 사용하세요. 예시 프롬프트: “내 ‘summarize’ skill을 가져와줘”

semantic_search / get_conversion (지원 종료)

이 두 도구는 Library 이전부터 존재했습니다. 여전히 동작하지만 예전 history API를 통해 저장된 변환만 볼 수 있고 전체 Library는 보지 못합니다 — 새로운 통합에서는 대신 search_library와 get_library_items를 사용해야 합니다.

인증

서버는 다음 순서로 API 키를 확인합니다.

WEB2MD_API_KEY 환경 변수가 설정되어 있으면 그것을 사용합니다.
그렇지 않으면 ~/.web2md/config.json — CLI의 device-login 흐름인 npx web2md-cli login이 작성하는 것과 동일한 파일입니다. login을 한 번 실행하면 CLI와 MCP server 모두 별도의 env 블록 없이 자동으로 키를 인식합니다.

둘 다 찾을 수 없으면 서버는 시작되지만, 모든 도구 호출이 키를 설정하거나 login을 실행하라는 힌트와 함께 인증 오류를 반환합니다.

설정

Claude Desktop
Cursor
Windsurf

Claude Desktop 설정 파일을 여세요.

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

mcpServers 아래에 web2md 항목을 추가하세요.

{
  "mcpServers": {
    "web2md": {
      "command": "npx",
      "args": ["-y", "web2md-mcp-server"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

이미 npx web2md-cli login을 실행했다면 env 블록을 완전히 생략할 수 있습니다 — 서버가 ~/.web2md/config.json에서 키를 읽습니다.Claude Desktop을 재시작하세요. 도구 선택 목록에 Web2MD 도구가 나타납니다.

~/.cursor/mcp.json 파일을 열고 다음을 추가하세요.

{
  "mcpServers": {
    "web2md": {
      "command": "npx",
      "args": ["-y", "web2md-mcp-server"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

새 서버를 로드하려면 Cursor를 재시작하세요.

~/.windsurf/mcp.json 파일을 열고 다음을 추가하세요.

{
  "mcpServers": {
    "web2md": {
      "command": "npx",
      "args": ["-y", "web2md-mcp-server"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

새 서버를 로드하려면 Windsurf를 재시작하세요.

사용 예시

MCP server가 실행되면 AI 어시스턴트에서 자연어를 사용할 수 있습니다.

페이지를 Markdown으로 변환

사용자: 이 URL을 markdown으로 변환해줘: https://react.dev/learn/thinking-in-react어시스턴트: (convert_url 호출) “Thinking in React”의 변환된 Markdown입니다…

Library 검색 및 가져오기

사용자: 인증 관련 내용을 내 library에서 검색하고, 가장 최근 항목의 전체 내용을 가져와줘어시스턴트: (search_library 다음 get_library_items 호출) 인증 관련 항목 3개를 찾았습니다. 가장 최근 항목인 “OAuth 2.0 Guide”의 전체 내용입니다…

Library를 로컬에 동기화

사용자: 내 library를 ~/notes/web2md에 동기화해줘어시스턴트: (sync_library 호출) 새 항목 42개 동기화 완료, 118개는 이미 최신 상태, 실패 0개입니다.

Extension으로 일괄 변환

사용자: 이 Reddit 스레드 8개를 일괄 변환해줘: […]어시스턴트: (agent_batch_convert 호출) 8/8개 URL 변환에 성공했습니다.

저장된 Skill 적용

사용자: 내가 어떤 skill을 가지고 있는지 알려주고, 이 페이지에 “summarize”를 적용해줘: https://…어시스턴트: (list_skills 다음 skill: "summarize"로 agent_convert 호출) 페이지를 Markdown으로 변환하고 그 아래에 summarize skill을 적용했습니다…

한 대화 안에서 여러 도구를 조합해서 사용할 수 있습니다. 예: “내 library에서 React 문서를 검색하고, 가장 최근 항목의 전체 내용을 가져와줘.”

문제 해결

설정 후 도구가 나타나지 않음

설정 파일을 수정한 뒤 애플리케이션을 재시작했는지 확인하세요. 터미널에서 npx -y web2md-mcp-server가 정상적으로 실행되는지 확인하세요.

인증 오류

WEB2MD_API_KEY가 유효한 w2m_ 키인지, 또는 ~/.web2md/config.json에 키가 있는지 다시 확인하세요(확실하지 않다면 npx web2md-cli login을 다시 실행). API keys 페이지에서 키를 확인할 수 있습니다.

agent_convert / agent_batch_convert / bridge_convert_url 실패

이 도구들은 Web2MD extension이 설치된 Chrome이 열려 있어야 하며, agent_* 도구는 native host도 설치되어 있어야 합니다. 설정 방법은 Agent Bridge를 참고하세요.

npx가 패키지를 찾지 못함

먼저 패키지를 전역으로 설치해보세요: npm install -g web2md-mcp-server, 그 다음 command를 web2md-mcp-server로 변경하고 args 필드를 제거하세요.

시작하기

핵심 기능

고급

요금제

개요

사용 가능한 도구

convert_url

bridge_convert_url

agent_convert

agent_batch_convert

search_library

get_library_items

sync_library

list_skills

get_skill

semantic_search / get_conversion (지원 종료)

인증

설정

사용 예시

문제 해결

​개요

​사용 가능한 도구

​convert_url

​bridge_convert_url

​agent_convert

​agent_batch_convert

​search_library

​get_library_items

​sync_library

​list_skills

​get_skill

​semantic_search / get_conversion (지원 종료)

​인증

​설정

​사용 예시

​문제 해결

개요

사용 가능한 도구

convert_url

bridge_convert_url

agent_convert

agent_batch_convert

search_library

get_library_items

sync_library

list_skills

get_skill

semantic_search / get_conversion (지원 종료)

인증

설정

사용 예시

문제 해결