Related MCP Server Resources

Explore more AI models, providers, and integration options:

  • Explore AI Models
  • Explore AI Providers
  • Explore MCP Servers
  • LangDB Pricing
  • Documentation
  • AI Industry Blog
  • MCP Server for ArangoDB
  • SettleMint
  • MCP Filesystem Server
  • Git Spice Help MCP Server
  • Image Processor MCP Server
Back to MCP Servers
mcp-text-editor

mcp-text-editor

Public
tumf/mcp-text-editor

Provides line-oriented text file editing with safe concurrent access, token-efficient partial file loading, multi-file atomic operations, and robust conflict detection optimized for Model Context Protocol (MCP) integration with LLM tools.

python
0 tools
May 29, 2025
Updated Jun 4, 2025

Supercharge Your AI with mcp-text-editor

MCP Server

Unlock the full potential of mcp-text-editor through LangDB's AI Gateway. Get enterprise-grade security, analytics, and seamless integration with zero configuration.

Unified API Access
Complete Tracing
Instant Setup
Get Started Now

Free tier available • No credit card required

Instant Setup
99.9% Uptime
10,000+Monthly Requests

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:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json
{ "mcpServers": { "text-editor": { "command": "uvx", "args": [ "mcp-text-editor" ] } } }

or with docker:

{ "mcpServers": { "text-editor": { "command": "docker", "args": [ "run", "-i", "--rm", "--mount", "type=bind,src=/some/path/src,dst=/some/path/dst", "mcp/text-editor" ] } } }

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
  1. Install Python 3.11+
pyenv install 3.11.6 pyenv local 3.11.6
  1. Install uv (recommended) or pip
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Create virtual environment and install dependencies
uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e ".[dev]"

Requirements

  • Python 3.13+
  • POSIX-compliant operating system (Linux, macOS, etc.) or Windows
  • File system permissions for read/write operations

Installation

Run via uvx

uvx mcp-text-editor

Installing via Smithery

To install Text Editor Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-text-editor --client claude

Manual Installation

  1. Install Python 3.13+
pyenv install 3.13.0 pyenv local 3.13.0

Docker Installation

docker build --network=host -t mcp/text-editor .
  1. Install uv (recommended) or pip
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Create virtual environment and install dependencies
uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e ".[dev]"

Usage

Start the server:

python -m mcp_text_editor

Start the server with docker:

docker run -i --rm --mount "type=bind,src=/some/path/src,dst=/some/path/dst" mcp/text-editor

with inspector:

npx @modelcontextprotocol/inspector docker run -i --rm --mount "type=bind,src=/some/path/src,dst=/some/path/dst" mcp/text-editor

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:

{ "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 file
  • line_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 } ] }

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:

{ "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 " }, { "start": 15, "end": null, // null means end of file "range_hash": "sha256-hash-of-content-being-replaced", "contents": "Content to append " } ] } ] }

Important Notes:

  1. Always get the current hash and range_hash using get_text_file_contents before editing
  2. Patches are applied from bottom to top to handle line number shifts correctly
  3. Patches must not overlap within the same file
  4. Line numbers are 1-based
  5. end: null can be used to append content to the end of file
  6. File encoding must match the encoding used in get_text_file_contents

Success 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
        }
    ]
})
  1. Edit file content:
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 " } ] } ] })
  1. Handle conflicts:
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

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

  1. Permission Denied

    • Check file and directory permissions
    • Ensure the server process has necessary read/write access
  2. 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
  3. Encoding Issues

    • Verify file encoding matches the specified encoding
    • Use utf-8 for new files
    • Check for BOM markers in files
  4. Connection Issues

    • Verify the server is running and accessible
    • Check network configuration and firewall settings
  5. Performance Issues

    • Consider using smaller line ranges for large files
    • Monitor system resources (memory, disk space)
    • Use appropriate encoding for file type

Development

Setup

  1. Clone the repository
  2. Create and activate a Python virtual environment
  3. Install development dependencies: uv pip install -e ".[dev]"
  4. 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:

# 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%

Project Structure

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

License

MIT

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests and code quality checks
  5. 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.

Publicly Shared Threads0

Discover shared experiences

Shared threads will appear here, showcasing real-world applications and insights from the community. Check back soon for updates!

Share your threads to help others
Related MCPs5
  • MCP Server for ArangoDB
    MCP Server for ArangoDB

    Model Context Protocol server enabling seamless interaction with ArangoDB through core database oper...

    7 tools
    Added May 30, 2025
  • SettleMint
    SettleMint

    Provides a robust Model Context Protocol interface with development tools and project management cap...

    Added May 30, 2025
  • MCP Filesystem Server
    MCP Filesystem Server

    Model Context Protocol server enabling secure, efficient filesystem operations with smart context ma...

    Added May 30, 2025
  • Git Spice Help MCP Server
    Git Spice Help MCP Server

    Provides Model Context Protocol integration with Cursor IDE for real-time git-spice documentation se...

    1 tools
    Added May 30, 2025
  • Image Processor MCP Server
    Image Processor MCP Server

    A TypeScript-based Model Context Protocol server enabling creation, access, and summarization of tex...

    2 tools
    Added May 30, 2025