An MCP server that provides line-oriented text file editing capabilities through a standardized API. Optimized for LLM tools with efficient partial file access to minimize token usage.
A Model Context Protocol (MCP) server that provides line-oriented text file editing capabilities through a standardized API. Optimized for LLM tools with efficient partial file access to minimize token usage.
To use this editor with Claude.app, add the following configuration to your prompt:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"text-editor": {
"command": "uvx",
"args": [
"mcp-text-editor"
]
}
}
}
MCP Text Editor Server is designed to facilitate safe and efficient line-based text file operations in a client-server architecture. It implements the Model Context Protocol, ensuring reliable file editing with robust conflict detection and resolution. The line-oriented approach makes it ideal for applications requiring synchronized file access, such as collaborative editing tools, automated text processing systems, or any scenario where multiple processes need to modify text files safely. The partial file access capability is particularly valuable for LLM-based tools, as it helps reduce token consumption by loading only the necessary portions of files.
pyenv install 3.11.6
pyenv local 3.11.6
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
uvx mcp-text-editor
To install Text Editor Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install mcp-text-editor --client claude
pyenv install 3.13.0
pyenv local 3.13.0
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
Start the server:
python -m mcp_text_editor
The server provides several tools for text file manipulation:
Get the contents of one or more text files with line range specification.
Single Range Request:
{
"file_path": "path/to/file.txt",
"line_start": 1,
"line_end": 10,
"encoding": "utf-8" // Optional, defaults to utf-8
}
Multiple Ranges Request:
{
"files": [
{
"file_path": "file1.txt",
"ranges": [
{"start": 1, "end": 10},
{"start": 20, "end": 30}
],
"encoding": "shift_jis" // Optional, defaults to utf-8
},
{
"file_path": "file2.txt",
"ranges": [
{"start": 5, "end": 15}
]
}
]
}
Parameters:
file_path: Path to the text fileline_start/start: Line number to start from (1-based)line_end/end: Line number to end at (inclusive, null for end of file)encoding: File encoding (default: "utf-8"). Specify the encoding of the text file (e.g., "shift_jis", "latin1")Single Range Response:
{
"contents": "File contents",
"line_start": 1,
"line_end": 10,
"hash": "sha256-hash-of-contents",
"file_lines": 50,
"file_size": 1024
}
Multiple Ranges Response:
{
"file1.txt": [
{
"content": "Lines 1-10 content",
"start": 1,
"end": 10,
"hash": "sha256-hash-1",
"total_lines": 50,
"content_size": 512
},
{
"content": "Lines 20-30 content",
"start": 20,
"end": 30,
"hash": "sha256-hash-2",
"total_lines": 50,
"content_size": 512
}
],
"file2.txt": [
{
"content": "Lines 5-15 content",
"start": 5,
"end": 15,
"hash": "sha256-hash-3",
"total_lines": 30,
"content_size": 256
}
]
}
Apply patches to text files with robust error handling and conflict detection. Supports editing multiple files in a single operation.
Request Format:
{
"files": [
{
"file_path": "file1.txt",
"hash": "sha256-hash-from-get-contents",
"encoding": "utf-8", // Optional, defaults to utf-8
"patches": [
{
"start": 5,
"end": 8,
"range_hash": "sha256-hash-of-content-being-replaced",
"contents": "New content for lines 5-8\n"
},
{
"start": 15,
"end": null, // null means end of file
"range_hash": "sha256-hash-of-content-being-replaced",
"contents": "Content to append\n"
}
]
}
]
}
Important Notes:
end: null can be used to append content to the end of fileSuccess Response:
{
"file1.txt": {
"result": "ok",
"hash": "sha256-hash-of-new-contents"
}
}
Error Response with Hints:
{
"file1.txt": {
"result": "error",
"reason": "Content hash mismatch",
"suggestion": "get", // Suggests using get_text_file_contents
"hint": "Please run get_text_file_contents first to get current content and hashes"
}
}
"result": "error",
"reason": "Content hash mismatch - file was modified",
"hash": "current-hash",
"content": "Current file content"
} }
### Common Usage Pattern
1. Get current content and hash:
```python
contents = await get_text_file_contents({
"files": [
{
"file_path": "file.txt",
"ranges": [{"start": 1, "end": null}] # Read entire file
}
]
})
result = await edit_text_file_contents({
"files": [
{
"path": "file.txt",
"hash": contents["file.txt"][0]["hash"],
"encoding": "utf-8", # Optional, defaults to "utf-8"
"patches": [
{
"line_start": 5,
"line_end": 8,
"contents": "New content\n"
}
]
}
]
})
if result["file.txt"]["result"] == "error":
if "hash mismatch" in result["file.txt"]["reason"]:
# File was modified by another process
# Get new content and retry
pass
The server handles various error cases:
Permission Denied
Hash Mismatch and Range Hash Errors
Encoding Issues
Connection Issues
Performance Issues
uv pip install -e ".[dev]"make allTests are located in the tests directory and can be run with pytest:
# Run all tests
pytest
# Run tests with coverage report
pytest --cov=mcp_text_editor --cov-report=term-missing
# Run specific test file
pytest tests/test_text_editor.py -v
Current test coverage: 90%
mcp-text-editor/
├── mcp_text_editor/
│ ├── __init__.py
│ ├── __main__.py # Entry point
│ ├── models.py # Data models
│ ├── server.py # MCP Server implementation
│ ├── service.py # Core service logic
│ └── text_editor.py # Text editor functionality
├── tests/ # Test files
└── pyproject.toml # Project configuration
MIT
This project uses Python type hints throughout the codebase. Please ensure any contributions maintain this.
All error cases should be handled appropriately and return meaningful error messages. The server should never crash due to invalid input or file operations.
New features should include appropriate tests. Try to maintain or improve the current test coverage.
All code should be formatted with Black and pass Ruff linting. Import sorting should be handled by isort.