The MCP Text Editor Server provides robust, line-based text file editing and manipulation optimized for LLM tools and collaborative workflows with concurrency control.
Read text files: Retrieve specific line ranges from multiple files
Create text files: Create new text files with specified content
Append to files: Add content to existing files
Delete content: Remove specific line ranges from files
Insert content: Insert text before or after specific lines
Patch files: Apply multiple line-based edits
Concurrency management: Uses SHA-256 hashes to detect and handle conflicts
Partial file access: Efficiently retrieve or modify specific line ranges
Multi-file operations: Perform operations on multiple files in a single request
Encoding support: Supports various text encodings (utf-8, shift_jis, latin1)
Security features: Includes file path validation
Integration for code coverage reporting, as indicated by the codecov badge in the README.
MCP Text Editor Server
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.
Quick Start for Claude.app Users
To use this editor with Claude.app, add the following configuration to your prompt:
or with docker:
Overview
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.
Key Benefits
Line-based editing operations
Token-efficient partial file access with line-range specifications
Optimized for LLM tool integration
Safe concurrent editing with hash-based validation
Atomic multi-file operations
Robust error handling with custom error types
Comprehensive encoding support (utf-8, shift_jis, latin1, etc.)
Features
Line-oriented text file editing and reading
Smart partial file access to minimize token usage in LLM applications
Get text file contents with line range specification
Read multiple ranges from multiple files in a single operation
Line-based patch application with correct handling of line number shifts
Edit text file contents with conflict detection
Flexible character encoding support (utf-8, shift_jis, latin1, etc.)
Support for multiple file operations
Proper handling of concurrent edits with hash-based validation
Memory-efficient processing of large files
Requirements
Python 3.11 or higher
POSIX-compliant operating system (Linux, macOS, etc.) or Windows
Sufficient disk space for text file operations
File system permissions for read/write operations
Install Python 3.11+
Install uv (recommended) or pip
Create virtual environment and install dependencies
Requirements
Python 3.13+
POSIX-compliant operating system (Linux, macOS, etc.) or Windows
File system permissions for read/write operations
Installation
Run via uvx
Installing via Smithery
To install Text Editor Server for Claude Desktop automatically via Smithery:
Manual Installation
Install Python 3.13+
Docker Installation
Install uv (recommended) or pip
Create virtual environment and install dependencies
Usage
Start the server:
Start the server with docker:
with inspector:
MCP Tools
The server provides several tools for text file manipulation:
get_text_file_contents
Get the contents of one or more text files with line range specification.
Single Range Request:
Multiple Ranges Request:
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:
Multiple Ranges Response:
patch_text_file_contents
Apply patches to text files with robust error handling and conflict detection. Supports editing multiple files in a single operation.
Request Format:
Important Notes:
Always get the current hash and range_hash using get_text_file_contents before editing
Patches are applied from bottom to top to handle line number shifts correctly
Patches must not overlap within the same file
Line numbers are 1-based
end: null
can be used to append content to the end of fileFile encoding must match the encoding used in get_text_file_contents
Success Response:
Error Response with Hints:
} }
Edit file content:
Handle conflicts:
Error Handling
The server handles various error cases:
File not found
Permission errors
Hash mismatches (concurrent edit detection)
Invalid patch ranges
Overlapping patches
Encoding errors (when file cannot be decoded with specified encoding)
Line number out of bounds
Security Considerations
File Path Validation: The server validates all file paths to prevent directory traversal attacks
Access Control: Proper file system permissions should be set to restrict access to authorized directories
Hash Validation: All file modifications are validated using SHA-256 hashes to prevent race conditions
Input Sanitization: All user inputs are properly sanitized and validated
Error Handling: Sensitive information is not exposed in error messages
Troubleshooting
Common Issues
Permission Denied
Check file and directory permissions
Ensure the server process has necessary read/write access
Hash Mismatch and Range Hash Errors
The file was modified by another process
Content being replaced has changed
Run get_text_file_contents to get fresh hashes
Encoding Issues
Verify file encoding matches the specified encoding
Use utf-8 for new files
Check for BOM markers in files
Connection Issues
Verify the server is running and accessible
Check network configuration and firewall settings
Performance Issues
Consider using smaller line ranges for large files
Monitor system resources (memory, disk space)
Use appropriate encoding for file type
Development
Setup
Clone the repository
Create and activate a Python virtual environment
Install development dependencies:
uv pip install -e ".[dev]"
Run tests:
make all
Code Quality Tools
Ruff for linting
Black for code formatting
isort for import sorting
mypy for type checking
pytest-cov for test coverage
Testing
Tests are located in the tests
directory and can be run with pytest:
Current test coverage: 90%
Project Structure
License
MIT
Contributing
Fork the repository
Create a feature branch
Make your changes
Run tests and code quality checks
Submit a pull request
Type Hints
This project uses Python type hints throughout the codebase. Please ensure any contributions maintain this.
Error Handling
All error cases should be handled appropriately and return meaningful error messages. The server should never crash due to invalid input or file operations.
Testing
New features should include appropriate tests. Try to maintain or improve the current test coverage.
Code Style
All code should be formatted with Black and pass Ruff linting. Import sorting should be handled by isort.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A line-oriented text file editor. Optimized for LLM tools with efficient partial file access to minimize token usage.
Related MCP Servers
- AsecurityAlicenseAqualityShell and file edit capabilities tightly coupled to provide a powerful coding experience. You can work with different modes: architect and code-writer for separate plan and implementation phase. You can get it to invoke any cli command, e.g., compiling, type checking, linting, github cli, pythonLast updated -6580Apache 2.0
- AsecurityAlicenseAqualityA coding agent toolkit that transforms LLMs into coding assistants capable of working directly on your codebase with semantic code retrieval and editing tools, providing IDE-like capabilities without requiring API subscriptions.Last updated -33MIT License
- AsecurityFlicenseAqualityProvides tools for making small, targeted edits to files using stream editors like sed and awk, enabling efficient modifications without full file replacement.Last updated -101
- -securityFlicense-qualityA command-line interface application that enables interaction with LLMs through document retrieval, command-based prompts, and extensible tool integrations using the Model Control Protocol architecture.Last updated -
Appeared in Searches
- A tool for finding and replacing text strings in files or code
- A tool similar to Cursor with agent-based functionalities
- Understanding File Structures
- How to increase a model's context window for handling large files
- A tool for uploading and analyzing files on MacBook with PDF and Word support, and converting them to Markdown