What can you do with this server?

The hwpConverMdMCP server converts HWP/HWPX (Hangul Word Processor) files into Markdown format via two MCP tools: * convert_hwp_to_md: Convert a local HWP/HWPX file by providing its filesystem path. Best for local or Docker volume-mounted environments where the MCP server and files share the same filesystem. * convert_hwp_content_to_md: Convert HWP/HWPX content supplied as a Base64-encoded string (with the original filename for format detection), returning Markdown text and an optional download URL. Best for remote, Kubernetes, or Flowise environments. Additional capabilities: * Integrate with MCP clients including Claude Desktop, Cursor, Claude Code, and Flowise * Communicate via stdio (local) or Streamable HTTP (web/remote clients) * Deploy via Docker or Kubernetes, with support for proxy settings and configurable timeouts for large files * Act as a protocol bridge between LLM applications and the underlying HWP conversion API

Which integrations are available for this server?

Converts HWP and HWPX (Hangul Word Processor) documents into Markdown format, allowing LLMs to process and analyze the content of Korean word processing files.

How do I use hwpConverMdMCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hwpConverMdMCP convert the report at /path/to/document.hwp to markdown" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

hwpConverMdMCP

by beomzh

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

hwpConverMdMCP

HWP/HWPX 파일을 Markdown으로 변환하는 hwpConverMd API의 MCP(Model Context Protocol) 서버입니다.

Claude Desktop, Cursor, Claude Code, Flowise 등 MCP 클라이언트에서 HWP 문서 변환 기능을 사용할 수 있습니다.

아키텍처

MCP 클라이언트 (Claude Desktop / Cursor / Flowise CustomFunction)
        │
        │  stdio 또는 Streamable HTTP (JSON-RPC + SSE)
        ▼
  hwpConverMdMCP (Node.js MCP Server)
        │
        │  HTTP (multipart/form-data)
        ▼
  hwpConverMd (Python FastAPI Server)
        │
        ├── HwpFastConverter (XML 직접 파싱, 고속)
        ├── HwpConverter (hwp5html 폴백)
        │
        ├── POST /api/v1/convert        → JSON (markdown + download_url)
        ├── POST /api/v1/convert/base64  → JSON (Base64 입력, Flowise용)
        ├── POST /api/v1/upload-md       → JSON (임의 MD 저장 → download_url 발급)
        └── GET  /api/v1/download/{file} → 파일 다운로드

Related MCP server: hwp-mcp

전제조건

Node.js >= 18.0.0
hwpConverMd Python 서버가 실행 중이어야 합니다

hwpConverMd 서버 실행

# Docker로 실행 (권장)
cd ../hwpConverMd
docker compose up --build

# 또는 직접 실행
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000

서버가 정상 동작하면 http://localhost:8000/ 에서 {"status": "ok"} 응답을 확인할 수 있습니다.

설치

npm install
npm run build

MCP Tools

Tool	설명	파라미터	응답
`convert_hwp_to_md`	로컬 파일 경로로 변환	`filePath`: 파일 경로	markdown 텍스트
`convert_hwp_content_to_md`	Base64 콘텐츠로 변환	`content`: Base64, `filename`: 파일명	markdown + `[DOWNLOAD_URL]`

convert_hwp_content_to_md 응답 형식

이 도구는 MCP content 배열로 두 가지 텍스트 블록을 반환합니다:

{
  "content": [
    { "type": "text", "text": "# 변환된 마크다운 내용..." },
    { "type": "text", "text": "[DOWNLOAD_URL]/api/v1/download/파일명.md" }
  ]
}

첫 번째 블록: 변환된 마크다운 전체 텍스트
두 번째 블록: [DOWNLOAD_URL] 접두사 + HWP API의 다운로드 경로 (없을 수도 있음)

사용법

1. Claude Desktop에서 사용 (stdio)

claude_desktop_config.json에 추가:

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

{
  "mcpServers": {
    "hwp-converter": {
      "command": "node",
      "args": ["/absolute/path/to/hwpConverMdMCP/dist/transport/stdio.js"],
      "env": {
        "HWP_API_URL": "http://localhost:8000"
      }
    }
  }
}

2. Cursor에서 사용 (stdio)

프로젝트 루트에 .cursor/mcp.json 생성:

{
  "mcpServers": {
    "hwp-converter": {
      "command": "node",
      "args": ["/absolute/path/to/hwpConverMdMCP/dist/transport/stdio.js"],
      "env": {
        "HWP_API_URL": "http://localhost:8000"
      }
    }
  }
}

3. Claude Code에서 사용 (stdio)

claude mcp add hwp-converter \
  -e HWP_API_URL=http://localhost:8000 \
  -- node /absolute/path/to/hwpConverMdMCP/dist/transport/stdio.js

4. Streamable HTTP 모드 (Flowise / 웹 클라이언트용)

# 빌드 후 실행
npm run start:http

# 또는 개발 모드
npm run dev:http

MCP 엔드포인트: http://localhost:3000/mcp

Docker Compose

루트 디렉토리의 docker-compose.yml로 전체 스택(API + MCP + Flowise)을 함께 기동합니다:

# 루트 디렉토리에서
cd ..
docker compose up -d --build

서비스	포트	URL
api	8000	http://localhost:8000/docs
mcp	3001	http://localhost:3001/mcp
flowise	3000	http://localhost:3000

MCP 컨테이너의 HWP_API_URL=http://api:8000 (Docker 내부 네트워크)

환경변수

변수	설명	기본값
`HWP_API_URL`	hwpConverMd API 서버 URL	`http://localhost:8000`
`MCP_HTTP_PORT`	Streamable HTTP 포트	`3000`

개발

npm install

npm run dev:stdio     # stdio 모드 개발
npm run dev:http      # HTTP 모드 개발
npm run build         # TypeScript 빌드

npm run start:stdio   # stdio 모드 실행
npm run start:http    # HTTP 모드 실행

Kubernetes 배포

매니페스트 구조

k8s_manifest/
├── common/
│   ├── namespace.yaml         # 네임스페이스
│   ├── default-deny.yaml      # 기본 NetworkPolicy deny-all
│   └── resource-quota.yaml    # 리소스 제한
└── mcp/
    ├── serviceaccount.yaml    # 전용 ServiceAccount
    ├── rbac.yaml              # 최소 권한 RBAC
    ├── configmap.yaml         # 설정
    ├── mcp-deployment.yaml    # Deployment + Service
    ├── networkpolicy.yaml     # MCP → API 통신 허용
    └── ingress.yaml           # 외부 접근

배포

# 공통 리소스
kubectl apply -f k8s_manifest/common/

# MCP 서버
kubectl apply -f k8s_manifest/mcp/

K8s 운영 시 주의사항

MCP 서버는 1대로 운영 (권장)

MCP 서버는 인메모리 세션을 사용합니다. 복수 Pod에서 운영하면 initialize 요청을 받은 Pod과 tools/call 요청을 받는 Pod이 달라져 "Server not initialized" 에러가 발생합니다.

# MCP는 1대 고정 (stateful)
kubectl scale deploy hwp-mcp --replicas=1

# HPA가 걸려있으면 제거
kubectl delete hpa hwp-mcp

MCP 서버는 프로토콜 중계만 하므로 (CPU 사용 거의 없음) 1대로 충분합니다. 실제 변환 부하는 HWP API가 담당하며 HPA로 스케일링됩니다.

복수 Pod이 필요한 경우 Ingress에 세션 어피니티를 추가하세요:

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "MCP_ROUTE"
nginx.ingress.kubernetes.io/session-cookie-max-age: "600"

Ingress 설정 (필수)

Base64 인코딩된 HWP 파일이 JSON body로 전송되므로 body size 제한과 타임아웃을 늘려야 합니다:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "360"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "360"

Flowise에서 호출 시 내부 URL 사용

Flowise CustomFunction에서 MCP를 호출할 때는 K8s 내부 서비스 URL을 사용하세요:

// K8s 내부 (권장) - Ingress 안 거침, body size 제한 없음
const MCP_URL = 'http://hwp-mcp-svc:3000/mcp';

// 외부 Ingress (비권장) - hairpin NAT, SSL, body size 제한
const MCP_URL = 'https://hwp-mcp.your-domain.com/mcp';

보안 설정

항목	적용 내용
ServiceAccount	서비스별 전용 SA, `automountServiceAccountToken: false`
RBAC	ConfigMap 읽기만 허용 (최소 권한)
SecurityContext	`runAsNonRoot`, `drop ALL capabilities`, `seccompProfile: RuntimeDefault`
NetworkPolicy	`default-deny-all` + 명시적 허용만 (mcp->api, ingress->mcp)

확인

# Pod 상태
kubectl get pods -l app=hwp-mcp

# MCP 초기화 테스트
kubectl port-forward svc/hwp-mcp-svc 3000:3000
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

MCP 도구 호출 방법

방법 A: MCP 클라이언트 앱 (Claude Desktop / Cursor)

설정 후 자연어로 요청하면 LLM이 자동으로 도구를 호출합니다:

"이 HWP 파일을 마크다운으로 변환해줘: /path/to/document.hwp"

방법 B: MCP Client SDK 프로그래밍

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(
  new StreamableHTTPClientTransport(new URL("http://localhost:3000/mcp"))
);

// 파일 경로로 변환 (로컬 환경)
const result = await client.callTool({
  name: "convert_hwp_to_md",
  arguments: { filePath: "/path/to/document.hwp" },
});

// Base64로 변환 (원격/K8s/Flowise 환경)
const result2 = await client.callTool({
  name: "convert_hwp_content_to_md",
  arguments: { content: base64String, filename: "document.hwp" },
});

방법 C: curl로 JSON-RPC 직접 호출

# 1. 세션 초기화
SESSION_ID=$(curl -si -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' \
  | grep -i mcp-session-id | awk -F': ' '{print $2}' | tr -d '\r')

echo "Session: $SESSION_ID"

# 2. Initialized 알림
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# 3. 도구 호출
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"convert_hwp_to_md","arguments":{"filePath":"/path/to/doc.hwp"}}}'

두 도구의 사용 시나리오

도구	언제 사용	환경
`convert_hwp_to_md`	MCP 서버와 같은 파일시스템	로컬, Docker volume mount
`convert_hwp_content_to_md`	파일시스템이 분리된 환경	K8s, Flowise, 원격 서버

LLM 연동

이 MCP 서버 자체가 LLM 연동 레이어입니다.

방식	설명	코드 필요
Claude Desktop/Cursor	config.json 설정만으로 자동 연동	없음
Claude Code	`claude mcp add` 명령으로 등록	없음
Flowise	CustomFunction에서 MCP JSON-RPC 호출	CustomFunction 코드
프로그래밍 (Anthropic API)	MCP Client + Claude API 조합	`examples/llm-with-mcp.ts`

Anthropic Claude API + MCP 연동 예제

ANTHROPIC_API_KEY=sk-ant-... npx tsx examples/llm-with-mcp.ts /path/to/doc.hwp "이 문서를 요약해줘"

자세한 코드는 examples/llm-with-mcp.ts를 참조하세요.

Available Tools

2 tools

convert_hwp_content_to_mdConvert HWP content to MarkdownA

Read-only

Base64로 인코딩된 HWP 또는 HWPX 파일 내용을 Markdown으로 변환합니다. 파일 경로 대신 파일 내용을 직접 전달할 때 사용합니다. filename은 포맷 감지를 위해 .hwp 또는 .hwpx 확장자를 포함해야 합니다.

ParametersJSON Schema

Name	Required	Description	Default
`content`	Yes	Base64로 인코딩된 HWP 또는 HWPX 파일 내용
`filename`	Yes	원본 파일명 (.hwp 또는 .hwpx 확장자 포함, 포맷 감지용)

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true and openWorldHint=true, covering safety and flexibility. The description adds context about filename requirements for format detection, but does not detail conversion limitations, error handling, or output specifics, leaving some behavioral aspects unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by usage context and parameter guidance, all in three concise sentences with no wasted words, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity, lack of output schema, and rich annotations, the description covers purpose, usage, and key parameter context well. However, it could be more complete by mentioning conversion accuracy or output format details, though annotations help mitigate this gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are fully documented in the schema. The description reiterates the purpose of content and filename but does not add significant semantic details beyond what the schema provides, aligning with the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('convert'), resource ('Base64-encoded HWP or HWPX file content'), and output format ('Markdown'), and distinguishes it from sibling tools by specifying 'when file content is passed directly instead of file path'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool ('when file content is passed directly instead of file path'), which implicitly suggests the alternative (sibling tool convert_hwp_to_md) is for file paths, providing clear context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_hwp_to_mdConvert HWP file to MarkdownA

Read-only

로컬 파일 경로의 HWP 또는 HWPX 파일을 Markdown으로 변환합니다. 서버 파일시스템에 존재하는 파일 경로를 지정해야 합니다.

ParametersJSON Schema

Name	Required	Description	Default
`filePath`	Yes	HWP 또는 HWPX 파일의 절대 또는 상대 경로

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate read-only and open-world hints, which the description aligns with by not contradicting them. However, it adds minimal behavioral context beyond annotations, such as specifying the server filesystem requirement, but lacks details on error handling or output format specifics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, consisting of two sentences that efficiently convey the tool's purpose and key usage requirement without unnecessary details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple input schema with full coverage and annotations providing safety hints, the description is adequately complete for a conversion tool. However, without an output schema, it could benefit from mentioning the return type or any limitations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents the 'filePath' parameter. The description adds no additional semantic details beyond what the schema provides, such as file format constraints or path examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('convert'), resource ('HWP or HWPX file'), and output format ('Markdown'), distinguishing it from the sibling tool 'convert_hwp_content_to_md' which likely handles content rather than file paths.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context by specifying that the file must exist on the server filesystem and requires a local file path, but does not explicitly state when to use this tool versus the sibling tool or any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

2 tool updatesv1.0.0Feb 25, 2026
- First observedconvert_hwp_content_to_md
- First observedconvert_hwp_to_md

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Disambiguation5/5

The two tools have clearly distinct purposes: one handles base64-encoded file content directly, while the other works with local file paths. Their descriptions explicitly differentiate the input methods, eliminating any ambiguity.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (convert_hwp_content_to_md and convert_hwp_to_md), using the same verb 'convert' and similar noun structures. The naming is predictable and readable throughout.

Tool Count4/5

With only 2 tools, the server is minimal but well-scoped for its purpose of converting HWP/HWPX files to Markdown. It covers both content-based and path-based inputs, though it might feel slightly thin for broader file processing tasks.

Completeness4/5

The server provides complete coverage for its core conversion functionality, supporting both direct content and file paths. A minor gap exists in not handling other file operations like validation or batch processing, but the essential workflow is fully covered.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Mdkit A
online.mdkit
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Developer Tools RAG Systems Data Platforms
31
PDF to Markdown (pdf2md.dev)
dev.pdf2md
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
AI & Machine Learning Image & Video Processing
2
inktomd MCP Server A
io.github.hadirizvi093
Convert files, URLs, and documents to clean, AI-ready Markdown via MCP.
File Systems Web Scraping Documentation Access
91
docbaseOAuth
io.github.krayinc
DocBase MCP server for AI agents
Documentation Access Search Developer Tools
2

Related MCP Servers

kordoc
Documentation Access App Automation
chrisryugj
A
license
Not graded
quality
A
maintenance
An MCP server that parses South Korean document formats like HWP, HWPX, and PDF into Markdown. It features specialized table reconstruction and security-hardened extraction optimized for administrative and public institution files.
Updated a day ago (2026-09-05 11:24 UTC)
18,276
1,792
MIT
hwp-mcp
Developer Tools File Systems
treesoop
A
license
A
quality
A
maintenance
An MCP server for reading, writing, and managing Korean Hangul Word Processor (HWP/HWPX) files. It allows users to extract content, fill templates, and create new documents directly through AI assistants.
Updated 2 months ago (2026-07-08 09:21 UTC)
34
248
80
MIT
jun-skills-hwpx-v2
Workplace & Productivity Content Management Systems
cjLee-cmd
A
license
A
quality
D
maintenance
Unified MCP server for converting Markdown to HWPX documents or generating new HWPX files from templates while preserving formatting.
Updated 5 months ago (2026-03-25 08:40 UTC)
7
MIT
hwp-mcp
Workplace & Productivity
ioneway72
A
license
Not graded
quality
D
maintenance
MCP server for reading and writing HWP/HWPX (Korean Hangul word processor) files, enabling document reading, text extraction, table extraction, image extraction, template filling, text replacement, and creation of new documents.
Updated a month ago (2026-08-11 00:01 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/beomzh/hwpConverMdMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

hwpConverMdMCP

아키텍처

전제조건

hwpConverMd 서버 실행

설치

MCP Tools

convert_hwp_content_to_md 응답 형식

사용법

1. Claude Desktop에서 사용 (stdio)

2. Cursor에서 사용 (stdio)

3. Claude Code에서 사용 (stdio)

4. Streamable HTTP 모드 (Flowise / 웹 클라이언트용)

Docker Compose

환경변수

개발

Kubernetes 배포

매니페스트 구조

배포

K8s 운영 시 주의사항

MCP 서버는 1대로 운영 (권장)

Ingress 설정 (필수)

Flowise에서 호출 시 내부 URL 사용

보안 설정

확인

MCP 도구 호출 방법

방법 A: MCP 클라이언트 앱 (Claude Desktop / Cursor)

방법 B: MCP Client SDK 프로그래밍

방법 C: curl로 JSON-RPC 직접 호출

두 도구의 사용 시나리오

LLM 연동

Anthropic Claude API + MCP 연동 예제

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

kordoc

hwp-mcp

jun-skills-hwpx-v2

hwp-mcp

Latest Blog Posts

MCP directory API