Content
# Tool List
[](https://mseep.ai/app/jkf87-hwp-mcp)
# HWP-MCP (Hangul Model Context Protocol)
[](https://github.com/jkf87/hwp-mcp)
HWP-MCP is a Model Context Protocol (MCP) server that allows AI models like Claude to control Hangul word processors. This project provides AI with the ability to automatically generate, edit, and manipulate Hangul documents.
## Key Features
- Document creation and management: Create, open, and save documents
- Text editing: Insert text, set font, and add paragraphs
- Table operations: Create tables, fill data, and set cell content
- Completed document generation: Automatically generate reports and letters based on templates
- Batch operations: Execute multiple operations at once
## System Requirements
- Windows operating system
- Hangul (HWP) program installed
- Python 3.7 or higher
- Required Python packages (see requirements.txt)
## Installation
1. Clone repository:
```bash
git clone https://github.com/jkf87/hwp-mcp.git
cd hwp-mcp
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. (Optional) Install MCP package:
```bash
pip install mcp
```
## Usage
### Using with Claude
Register the HWP-MCP server in the Claude desktop configuration file as follows:
```json
{
"mcpServers": {
"hwp": {
"command": "python",
"args": ["path/hwp-mcp/hwp_mcp_stdio_server.py"]
}
}
}
```
### Example of Key Features
#### Create a new document
```python
hwp_create()
```
#### Insert text
```python
hwp_insert_text("Enter the desired text.")
```
#### Create a table and input data
```python
# Create a table
hwp_insert_table(rows=5, cols=2)
# Fill the table with data
hwp_fill_table_with_data([
["Month", "Sales"],
["January", "120"],
["February", "150"],
["March", "180"],
["April", "200"]
], has_header=True)
# Fill the table with consecutive numbers
hwp_fill_column_numbers(start=1, end=10, column=1, from_first_cell=True)
```
#### Save the document
```python
hwp_save("path/document_name.hwp")
```
#### Batch operations example
```python
hwp_batch_operations([
{"operation": "hwp_create"},
{"operation": "hwp_insert_text", "params": {"text": "Title"}},
{"operation": "hwp_set_font", "params": {"size": 20, "bold": True}},
{"operation": "hwp_save", "params": {"path": "path/document_name.hwp"}}
])
```
## Project Structure
```
hwp-mcp/
├── hwp_mcp_stdio_server.py # Main server script
├── requirements.txt # Dependency package list
├── hwp-mcp-structure-explanation.md # Project structure explanation document
├── src/
│ ├── tools/
│ │ ├── hwp_controller.py # Core controller for Hangul control
│ │ └── hwp_table_tools.py # Specialized module for table-related functions
│ ├── utils/ # Utility functions
│ └── __tests__/ # Test modules
└── security_module/
└── FilePathCheckerModuleExample.dll # Security module
```
## Troubleshooting
### Security Module Issues
By default, the Hangul program displays a security warning when accessing files from outside. To bypass this, use the `FilePathCheckerModuleExample.dll` module. If registration of the security module fails, the functionality will still work, but a security dialog box may appear when opening/saving files.
### Failed to Connect to Hangul
If the Hangul program is not running, connection may fail. Ensure that the Hangul program is installed and functioning properly.
### Table Data Input Issues
There was an issue with the cursor position behaving unexpectedly when inputting data into tables, but this has been resolved in the current version. Data is accurately input into all cells of the table.
## Change Log
### 2025-03-27
- Improved table creation and data filling functions
- Resolved the issue of nested tables
- Separated table creation and data filling functions
- Added logic to check the current cursor position before creating a table
- Improved the function to fill existing tables with data
- Improved project management
- Added .gitignore file (excluding temporary files, cache files, etc.)
### 2025-03-25
- Improved table data input function
- Able to input data accurately from the first cell
- Improved cell selection and cursor position setting logic
- Added function to maintain cursor position when inserting text
- Added a dedicated tool module for tables (`hwp_table_tools.py`)
- Added `from_first_cell` option to `hwp_fill_column_numbers` function
## License
This project is distributed under the MIT license. See the [LICENSE](LICENSE) file for details.
## Contribution
1. Report issues or suggest features: Use GitHub issues.
2. Contribute code: Submit a Pull Request with changes.
## Related Projects
- [HWP SDK](https://www.hancom.com/product/sdk): Official SDK from Hancom
- [Cursor MCP](https://docs.cursor.com/context/model-context-protocol#configuration-locations)
- [Smithery](https://smithery.ai/server/@jkf87/hwp-mcp)
## Contact
For project inquiries, contact via GitHub issues or [Conanssam](https://www.youtube.com/@conanssam).
