hwpx-mcp
MCP server for reading, editing, and creating HWPX documents (한컴오피스 XML format).
Built on python-hwpx and the Model Context Protocol.
Installation```bash
Run directly with uvx (no install needed)
uvx hwpx-mcp
Or install with uv
uv tool install hwpx-mcp
## Claude Desktop Configuration
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):```json
{
"mcpServers": {
"hwpx": {
"command": "uvx",
"args": ["hwpx-mcp"]
}
}
}
To restrict file access to specific directories:```json
{
"mcpServers": {
"hwpx": {
"command": "uvx",
"args": ["hwpx-mcp", "--allowed-dirs", "/path/to/documents"]
}
}
}
## Claude Code Configuration
Add to `.mcp.json`:```json
{
"mcpServers": {
"hwpx": {
"command": "uvx",
"args": ["hwpx-mcp"]
}
}
}
Tools
Document Lifecycle
| Tool | Description |
|---|---|
open_document |
Open a .hwpx file, returns a doc_id |
create_document |
Create a new empty document |
save_document |
Save to disk (original path or new path) |
close_document |
Close and release from memory |
list_open_documents |
List all open documents |
Reading
| Tool | Description |
|---|---|
get_document_text |
Export content as text, HTML, or Markdown |
get_document_info |
Structural summary (sections, paragraph counts) |
list_paragraphs |
List paragraphs with index and text preview |
Editing
| Tool | Description |
|---|---|
add_paragraph |
Append a paragraph |
remove_paragraph |
Remove paragraph by index |
add_table |
Add a table with optional cell data |
replace_text |
Find and replace text across the document |
set_header_footer |
Set header and/or footer text |
Search
| Tool | Description |
|---|---|
find_by_tag |
Search for XML elements by tag name |
Example Workflow
create_document→ getdoc_idadd_paragraph(doc_id, "제목")→ add titleadd_table(doc_id, 3, 2, [["이름", "나이"], ["홍길동", "30"], ["김철수", "25"]])→ add tableset_header_footer(doc_id, header_text="보고서")→ set headersave_document(doc_id, "/path/to/output.hwpx")→ saveclose_document(doc_id)→ cleanup
License
This project is licensed under the MIT License.
Note on python-hwpx
This server depends on python-hwpx. The python-hwpx GitHub repository and README state MIT License, though the PyPI classifier indicates a non-commercial license. Please review the python-hwpx license for your use case.
