Content
# wps-mcp-server
`wps-mcp-server` is a Windows stdio MCP Server controlled by Python through the WPS Office COM interface. It allows MCP Clients like Claude Code and Codex to invoke local WPS to create, read, modify, and open WPS Writer documents, PDFs, and Excel/WPS spreadsheets.
## Features
Currently, 11 MCP tools are provided:
- `create_document`: Create a WPS Writer/Word document and save it to the desktop.
- `write_document`: Append or overwrite content to an existing document.
- `read_document`: Read document text, returning up to 3000 characters.
- `create_pdf`: Create and export a PDF using WPS Writer.
- `read_pdf`: Read text-based PDFs, prioritizing PyMuPDF/pypdf and falling back to WPS.
- `modify_pdf`: Append text and save as a new PDF or overwrite with new content.
- `create_spreadsheet`: Create a WPS spreadsheet/Excel file, writing headers and data rows.
- `read_spreadsheet`: Read a specified worksheet and range, returning JSON text.
- `write_spreadsheet`: Write a 2D array starting from a specified cell.
- `modify_spreadsheet`: Set cell values or clear a range.
- `open_file`: Open `.docx/.doc/.wps/.xlsx/.xls/.et/.pdf` files with WPS.
## System Requirements
- Windows desktop environment.
- WPS Office installed locally.
- WPS COM automation available:
- Writer: `KWps.Application`
- Spreadsheets: `KET.Application`
- Python 3.9 or higher.
- Required dependency: `pywin32`.
This project does not support macOS, Linux, WSL, or remote server environments without a desktop or COM.
## Installation
Install from GitHub:
```bash
pip install "git+https://github.com/2365203723/wps-mcp-server.git"
```
For more stable PDF text reading, install optional PDF dependencies:
```bash
pip install "wps-mcp-server[pdf] @ git+https://github.com/2365203723/wps-mcp-server.git"
```
Verify the command is available:
```bash
mcp-wps
```
Running `mcp-wps` directly without CLI output is normal; it is a stdio MCP Server that waits for MCP Client JSON-RPC messages via stdin.
## Claude Code Configuration
Recommended configuration with Claude Code command:
```bash
claude mcp add wps -- mcp-wps
```
For user-level configuration, if your Claude Code version supports scope:
```bash
claude mcp add --scope user wps -- mcp-wps
```
If `mcp-wps` is not in PATH, use the Python module method:
```bash
claude mcp add wps -- python -m wps_server
```
Alternatively, create or modify `.claude/mcp.json`:
```json
{
"mcpServers": {
"wps": {
"type": "stdio",
"command": "mcp-wps",
"args": [],
"env": {}
}
}
}
```
For Python startup:
```json
{
"mcpServers": {
"wps": {
"type": "stdio",
"command": "python",
"args": ["-m", "wps_server"],
"env": {}
}
}
}
```
Restart Claude Code and confirm `wps` MCP tools are visible.
## Codex Configuration
Edit the Codex configuration file:
```text
~/.codex/config.toml
```
Add:
```toml
[mcp_servers.wps]
type = "stdio"
command = "mcp-wps"
args = []
startup_timeout_sec = 20
tool_timeout_sec = 120
```
For Python startup if `mcp-wps` is not in PATH:
```toml
[mcp_servers.wps]
type = "stdio"
command = "python"
args = ["-m", "wps_server"]
startup_timeout_sec = 20
tool_timeout_sec = 120
```
On Windows, if Codex cannot directly launch Python:
```toml
[mcp_servers.wps]
type = "stdio"
command = "cmd"
args = ["/c", "python", "-m", "wps_server"]
startup_timeout_sec = 20
tool_timeout_sec = 120
```
Restart Codex.
## Local Protocol Testing
Test `tools/list` without opening WPS:
```bash
python - <<'PY'
import json
import subprocess
p = subprocess.Popen(
["mcp-wps"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
text=True,
encoding="utf-8",
)
p.stdin.write(json.dumps({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}, ensure_ascii=False) + "\n")
p.stdin.flush()
print(p.stdout.readline())
p.stdin.write(json.dumps({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}, ensure_ascii=False) + "\n")
p.stdin.flush()
print(p.stdout.readline())
p.terminate()
PY
```
## Precautions
- Tools launch or connect to local WPS via COM, potentially popping up WPS windows.
- Creation tools save to the current user's desktop by default.
- PDF modification is not professional PDF editing; complex layouts are not guaranteed.
- Scanned PDFs usually require OCR for text extraction.
- File paths should use absolute paths.
- Write/modify tools save files; confirm target file paths first.
## FAQs
### `ModuleNotFoundError: No module named 'win32com'`
Install `pywin32`:
```bash
pip install pywin32
```
### `Invalid class string` or WPS COM object creation failure
Typically, WPS Office is not installed, not properly registered for COM, or the environment is not a Windows desktop. Manually open WPS once and retry; if it still fails, try repairing or reinstalling WPS Office.
### Running `mcp-wps` appears to hang
This is normal behavior. `mcp-wps` is a stdio MCP Server waiting for MCP Client JSON-RPC messages.
### Incomplete PDF reading
PDF text extraction depends on file content. Install optional PDF dependencies:
```bash
pip install PyMuPDF pypdf
```
Scanned PDFs require OCR; this project does not provide OCR.
### Can it be used on Linux, macOS, or WSL?
No. This project depends on Windows COM and local WPS Office.
## Development Verification
```bash
python -m py_compile wps_server.py
python -m pip install .
python -c "import wps_server; print(wps_server.__version__); print(callable(wps_server.main))"
python -m build
```
## License
MIT
