HWP MCP Server

MCP (Model Context Protocol) server that enables LLMs to read and modify binary HWP (한글) documents via the HWP COM API.

Architecture

LLM ↔ MCP Server (Python/FastMCP) ↔ PowerShell Bridge (JSON stdin/stdout) ↔ HWP COM API ↔ 한글

Python MCP server manages a long-running PowerShell subprocess that hosts HWP COM objects.

Requirements

• Windows (HWP COM API is Windows-only)
• 한컴오피스 한글 installed (provides HWP COM server)
• PowerShell 5.1+ (included with Windows)
• Python >= 3.11

Installation

uv pip install -e .

Usage

Run MCP Server

python -m hwp_mcp.server

Claude Desktop Config

{
  "mcpServers": {
    "hwp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/hwp-mcp", "hwp-mcp"]
    }
  }
}

MCP Tools (140)

HWP COM API 199 HParameterSet 100% coverage

Document Management (5)

Tool	Description
open_document	Open HWP document
close_document	Close document
list_open_documents	List open documents
save_document	Save document
save_document_as	Save as different name/format

Read (5)

Tool	Description
get_document_text	Extract full text
get_paragraphs	Get paragraph list
get_tables	Get table list
get_table_data	Get table data (2D array)
search_text	Search text

Write (5)

Tool	Description
replace_text	Replace text
insert_text	Insert text
set_table_cell_text	Set table cell text
append_paragraph	Append paragraph
set_text_file	Set document content from text data

Formatting (3)

Tool	Description
set_text_style	Character formatting (font, size, bold, color, etc.)
set_paragraph_style	Paragraph formatting (alignment, line spacing)
set_page_style	Page formatting (margins, orientation)

Table (3)

Tool	Description
create_table	Create table
add_table_row	Add table row
delete_table_row	Delete table row

Advanced (5)

Tool	Description
run_hwp_action	Execute arbitrary HWP action (power user)
convert_to_hwpx	Convert HWP → HWPX
convert_to_pdf	Convert HWP → PDF
batch_convert_files	Batch convert files (HWP, PDF, DOCX, etc.)
set_file_security	File security settings (copy/print restriction)

Cursor & Navigation (11)

Tool	Description
move_cursor	Move cursor to specified position
get_cursor_position	Get current cursor position
set_cursor_position	Set cursor position (list, para, pos)
get_pos_by_set	Get cursor position as set
set_pos_by_set	Set cursor position from set
get_selected_pos_by_set	Get selection start/end positions
select_text	Select text range by coordinates
get_selection_info	Get current selection info
clear_selection	Clear selection
delete_selection	Delete selected content
init_scan	Initialize document scan

Field (12)

Tool	Description
create_field	Create named field (template placeholder)
field_exists	Check if field exists
get_field_list	Get all field names
get_field_text	Read field text
put_field_text	Set field text
get_current_field	Get field name at cursor
set_current_field_name	Set current field name
move_to_field	Move cursor to field
rename_field	Rename field
modify_field_properties	Modify field properties
set_field_ctrl_properties	Set field control properties
batch_fill_fields	Batch fill multiple fields

Advanced Table (11)

Tool	Description
add_table_column	Add table column
delete_table_column	Delete table column
merge_table_cells	Merge cells
split_table_cell	Split cell
set_table_cell_style_adv	Cell style (background, vertical alignment)
set_table_border_adv	Table border style
table_to_text	Table → text conversion
text_to_table	Text → table conversion
swap_table_row_col	Swap table rows/columns
apply_table_template	Apply table template

Enhanced Formatting (5)

Tool	Description
set_char_shape	Extended character properties (kerning, spacing, shadow, etc.)
set_bullet_style	Bullet style
set_numbering_style	Numbering style
set_tab_definition	Tab stops
manage_style	Create/delete/apply styles

Page & Section (10)

Tool	Description
set_section_definition	Section definition (binding margin, text flow)
set_page_border	Page border and background
set_columns	Multi-column layout
set_page_number	Page number
set_header_footer	Header/footer
set_footnote_style	Footnote style
set_master_page	Master page
set_page_hiding	Hide page elements (header/footer, etc.)
set_page_num_ctrl	Page number control (restart numbering)
set_text_direction	Text direction (horizontal/vertical)

Image & Equation (3)

Tool	Description
insert_picture	Insert picture
insert_background_picture	Insert background picture
create_equation	Insert equation

Form Control (3)

Tool	Description
insert_form_control	Insert form control (button, checkbox, etc.)
set_form_properties	Set form control properties
get_form_data	Read form data

Document Info (5)

Tool	Description
get_document_info	Document metadata (page count, modified state)
get_document_summary	Document summary (title, author)
get_page_text	Extract specific page text
get_page_count	Total page count
export_page_as_image	Export page as image

Print & Export (3)

Tool	Description
print_document	Print document
set_watermark	Set watermark (text/image)
save_as_image	Save document as image

Utility (4)

Tool	Description
convert_units	Unit conversion (mm, pt, hwpunit)
rgb_color	RGB/Hex → HWP color value
run_macro	Run HWP macro
get_file_info	File metadata (without opening)

Bookmark & Hyperlink (6)

Tool	Description
insert_bookmark	Insert bookmark
insert_hyperlink	Insert hyperlink
hyperlink_jump	Jump to hyperlink target
insert_index_mark	Insert index mark
insert_auto_number	Insert auto number field
insert_cross_reference	Insert cross reference

Header/Footer & Caption (2)

Tool	Description
set_drop_cap	Drop cap (decorative first letter)
set_caption	Table/image caption

Document Operations (8)

Tool	Description
sort_text	Sort text
spell_check	Spell check
set_track_changes	Track changes
mail_merge	Mail merge
make_table_of_contents	Generate table of contents
insert_file	Insert another file
set_password	Document password
save_block	Save selection to file

Compatibility & Settings (3)

Tool	Description
set_compatible_document	Document compatibility mode
set_view_properties	HWP view properties (zoom, view mode, etc.)
set_engine_properties	HWP engine properties (spell check, auto-save, etc.)

Control & Object (4)

Tool	Description
delete_ctrl	Delete selected control
find_ctrl	Find control
check_x_object	Check X object existence
release_scan	Release scan resources

Style & Script (4)

Tool	Description
import_style	Import style
export_style	Export style
run_script	Run HWP script
get_script_source	Get script source

System & Security (11)

Tool	Description
register_module	Register COM module
set_drm_authority	DRM authority
lock_command	Lock/unlock command
is_command_lock	Check command lock status
set_message_box_mode	Message box mode
get_message_box_mode	Get message box mode
is_action_enable	Check action enabled
replace_action	Replace action handler
get_hwp_property	Get HWP COM property
set_hwp_property	Set HWP COM property
hwp_enum	String → HWP enum value

HParameterSet Actions (10)

Tool	Description	HParameterSet Count
hwp_table_param_action	Table actions	14
hwp_file_param_action	File actions	11
hwp_draw_param_action	Draw object actions	22
hwp_shape_param_action	Shape actions	6
hwp_style_param_action	Style/border actions	6
hwp_form_param_action	Form actions	13
hwp_doc_info_param_action	Document info actions	9
hwp_hanja_param_action	Hanja/conversion actions	11
hwp_selection_param_action	Selection/position actions	6
hwp_misc_param_action	Miscellaneous actions	69

Project Structure

hwp-mcp/
├── src/hwp_mcp/
│   ├── __init__.py
│   ├── _core.py         # FastMCP instance & shared helpers
│   ├── server.py        # Entry point, imports all tool modules
│   ├── bridge.py        # PowerShell subprocess manager
│   ├── commands.py      # JSON command builders
│   └── tools/           # MCP tool definitions (140 tools)
│       ├── cursor.py
│       ├── doc_info.py
│       ├── document.py
│       ├── drawing.py
│       ├── field.py
│       ├── form.py
│       ├── formatting.py
│       ├── hparam.py
│       ├── hwpobject.py
│       ├── page_section.py
│       ├── print_export.py
│       ├── system.py
│       ├── table.py
│       ├── text.py
│       └── utility.py
├── scripts/
│   ├── hwp_bridge.ps1   # PowerShell COM bridge dispatcher
│   └── handlers/        # 12 handler modules
│       ├── document.ps1
│       ├── text.ps1
│       ├── table.ps1
│       ├── style_format.ps1
│       ├── action.ps1
│       ├── cursor_selection.ps1
│       ├── field.ps1
│       ├── draw_object.ps1
│       ├── form_control.ps1
│       ├── document_info.ps1
│       ├── print_export.ps1
│       ├── utility.ps1
│       └── hwpobject_methods.ps1
├── tests/
│   ├── test_bridge.py   # Bridge unit tests
│   ├── test_commands.py # Command builder unit tests
│   └── test_server.py   # Server tool unit tests
└── pyproject.toml

Development

uv pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/

Limitations

• Windows only: HWP COM API requires Windows
• 한글 required: 한컴오피스 한글 must be installed
• Binary HWP only: HWPX (XML-based) needs a separate server

License

MIT