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 the Hangul word processor (HWP). This project provides AI with the ability to automatically generate, edit, and manipulate Hangul documents.
## Key Features
- Document creation and management: New document creation, open, and save functions
- Text editing: Text insertion, font settings, and paragraph addition
- Table operations: Table creation, data filling, and cell content setting
- Completed document creation: Automatic generation of template-based reports and letters
- Batch operations: Batch function to execute multiple operations at once
## System Requirements
- Windows operating system
- Hangul (HWP) program installed
- Python 3.7 or higher
- Required Python packages (refer to requirements.txt)
## Installation Method
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 settings 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 operation 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 # Module specialized 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 externally. 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.
### Hangul Connection Failure
If the Hangul program is not running, the connection may fail. Ensure that the Hangul program is installed and functioning properly.
### Table Data Input Issues
There was an issue where the cursor position behaved 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 only 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 table-specific tool module (`hwp_table_tools.py`)
- Added `from_first_cell` option to `hwp_fill_column_numbers` function
## License
This project is distributed under the MIT license. Refer to the [LICENSE](LICENSE) file for details.
## Contribution Method
1. Report issues or suggest features: Use GitHub issues.
2. Code contribution: 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, use GitHub issues or contact [Conan](https://www.youtube.com/@conanssam).
