rope-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rope-mcp-server rename function calculate_total to compute_sum in src/utils.py"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
rope-mcp-server
A Model Context Protocol (MCP) server that provides Python refactoring capabilities powered by the Rope library. Enables AI agents like Claude to perform safe, project-wide refactoring operations.
Features
Move Symbol - Move classes and functions between files with automatic import updates
Move Module - Move entire modules or packages to different folders
Move and Rename Module - Move module to folder and rename (e.g.,
foo_extra.py→foo/extra.py)Convert Module to Init - Transform
foo.pyintofoo/__init__.py(no import changes!)Convert Module to Package - Transform
foo.pyintofoo/foo.pywith import updatesRename Symbol - Rename variables, functions, classes across entire projects
Extract Method - Extract code blocks into new methods
Inline Variable - Inline variables at all usage sites
List Symbols - Discover top-level symbols in Python files
All operations are project-aware and automatically update imports and references throughout your codebase.
Related MCP server: Rope MCP
Installation
Quick Start with Claude Code (recommended)
# Global installation (all projects)
claude mcp add rope-refactor uvx rope-mcp-server -s user
# Or for current project only
claude mcp add rope-refactor uvx rope-mcp-server -s localFrom PyPI
pip install rope-mcp-serverUsage with Claude Code
claude mcp add rope-refactor uvx rope-mcp-server -s user
claude mcp list # verifyThat's it.
Available Tools
list_symbols
List all top-level symbols (classes, functions, variables) in a Python file.
project_path: /path/to/your/project
file_path: src/models.pymove_symbol
Move a class or function to another file. Automatically updates all imports.
project_path: /path/to/your/project
source_file: src/models.py
symbol_name: UserModel
dest_file: src/users/models.pymove_module
Move a module or package to another folder. Automatically updates all imports.
project_path: /path/to/your/project
module_path: src/utils.py
dest_folder: src/libconvert_module_to_init (recommended)
Convert a module file into a package by moving it to __init__.py. No import changes needed!
This is the recommended way to convert a module to a package. After conversion, you can use move_module to move related files (like foo_mixins.py) into the new package.
project_path: /path/to/your/project
module_path: app/views/customer_order.pyBefore:
app/views/customer_order.py
app/views/customer_order_mixins.pyAfter running convert_module_to_init:
app/views/customer_order/__init__.py (was customer_order.py)
app/views/customer_order_mixins.py (move this next with move_module)Import from app.views.customer_order import X stays unchanged!
move_and_rename_module
Move a module to a folder and optionally rename it. Perfect for moving related files (like _mixins.py, _extra.py) into a package created with convert_module_to_init.
Auto-detection: If the module name starts with the destination folder name + underscore, it strips that prefix automatically.
Rope bug workaround: This tool includes a workaround for a Rope bug that crashes when a file has imports from BOTH the destination package AND the module being moved. Such files are temporarily hidden during the move, then their imports are fixed manually.
project_path: /path/to/your/project
module_path: app/views/customer_order_mixins.py
dest_folder: app/views/customer_order
new_name: mixins # Optional - auto-detected from prefixBefore:
app/views/customer_order/__init__.py
app/views/customer_order_mixins.pyImport: from app.views.customer_order_mixins import MyMixin
After:
app/views/customer_order/__init__.py
app/views/customer_order/mixins.pyImport: from app.views.customer_order.mixins import MyMixin
convert_module_to_package
Convert a module file into a package with the same name. Transforms foo.py into foo/foo.py while updating all imports project-wide.
Use this when you want the original module content in a submodule, not in __init__.py.
project_path: /path/to/your/project
module_path: app/views/service_contractor.pyBefore:
app/views/service_contractor.pyImport: from app.views.service_contractor import MyClass
After:
app/views/service_contractor/
├── __init__.py
└── service_contractor.pyImport: from app.views.service_contractor.service_contractor import MyClass
rename_symbol
Rename a symbol across the entire project.
project_path: /path/to/your/project
file_path: src/utils.py
symbol_name: old_function_name
new_name: new_function_nameextract_method
Extract a code region into a new method.
project_path: /path/to/your/project
file_path: src/service.py
start_line: 15
start_col: 4
end_line: 20
end_col: 30
new_name: extracted_helperinline_variable
Inline a variable at all usage sites.
project_path: /path/to/your/project
file_path: src/handler.py
variable_name: temp_result
line: 42close_rope_project
Close a Rope project to free memory. Call when done with refactoring.
project_path: /path/to/your/projectDevelopment
# Install dependencies
uv sync
# Run tests
uv run pytest tests/ -v
# Run server locally
uv run python -m rope_mcp_server.serverHow it works
This server wraps the Rope refactoring library and exposes its capabilities via the Model Context Protocol. When Claude (or any MCP-compatible agent) needs to refactor Python code, it can use these tools to perform safe, AST-aware transformations that preserve code correctness.
Key implementation details:
Project caching - Rope projects are cached to avoid re-parsing on every operation
AST-based offset calculation - Symbol locations are computed via Python's AST module for accuracy
Automatic import handling - Rope handles all import updates when moving/renaming symbols
Limitations
Only supports Python code (Rope limitation)
Moving methods between classes requires the target class to exist
Large projects may have slower initial indexing
Rope bug workaround: Files with imports from both the destination package and the module being moved are handled specially (hidden during move, then imports fixed manually) - see
move_and_rename_module
License
MIT
Contributing
Contributions welcome! Please open an issue first to discuss what you would like to change.
Available Tools
10 toolsclose_rope_projectA
Close a Rope project and release resources.
Call this when done with refactoring to free memory.
Args: project_path: Root directory of the Python project
Returns: JSON with success status
Inputs: project_path (required). Returns: result
convert_module_to_initA
Convert a module file into a package by moving it to init.py.
Transforms foo.py into foo/__init__.py. No import changes needed
since the import path stays the same!
Example:
views/customer_order.py becomes views/customer_order/__init__.py
Import from views.customer_order import X stays unchanged.
This is the recommended way to convert a module to a package when you want to later split it into multiple files.
Args: project_path: Root directory of the Python project module_path: Path to module file (relative to project_path), e.g. "app/views/foo.py"
Returns: JSON with success status and new path
Inputs: project_path (required), module_path (required). Returns: result
convert_module_to_packageA
Convert a module file into a package with the same name.
Transforms foo.py into foo/foo.py while updating all imports project-wide.
Example:
views/service_contractor.py becomes views/service_contractor/service_contractor.py
All imports like from views.service_contractor import X
become from views.service_contractor.service_contractor import X
This is a two-step process using Rope:
Move module to a temporary package (different name to trigger import updates)
Rename the temporary package to the original module name
Args: project_path: Root directory of the Python project module_path: Path to module file (relative to project_path), e.g. "app/views/foo.py"
Returns: JSON with success status and list of changed files
Inputs: project_path (required), module_path (required). Returns: result
extract_methodA
Extract a code region as a new method.
Args: project_path: Root directory of the Python project file_path: File path relative to project_path start_line: Start line (1-based) start_col: Start column (0-based) end_line: End line (1-based) end_col: End column (0-based) new_name: Name for the extracted method
Returns: JSON with success status and list of changed files
Inputs: project_path (required), file_path (required), start_line (required), start_col (required), +3 more. Returns: result
inline_variableA
Inline a variable at all usage sites.
Args: project_path: Root directory of the Python project file_path: File path relative to project_path variable_name: Name of the variable to inline line: Line number where variable is defined (1-based)
Returns: JSON with success status and list of changed files
Inputs: project_path (required), file_path (required), variable_name (required), line (required). Returns: result
list_symbolsA
List all top-level symbols in a Python file.
Args: project_path: Root directory of the Python project file_path: File path relative to project_path
Returns: JSON with symbols: [{"name": "Foo", "type": "class", "line": 5, "byte_offset": 42}, ...]
Inputs: project_path (required), file_path (required). Returns: result
move_and_rename_moduleA
Move a module to a folder and optionally rename it.
This is a two-step operation:
Move module to destination folder
Rename the module (if new_name provided or auto-detected)
Auto-detection: If module is foo_bar.py and dest is foo/,
it will automatically strip the foo_ prefix → foo/bar.py
Includes workaround for Rope bug: Files that import from BOTH the destination package AND the module being moved are temporarily hidden during the move, then their imports are fixed manually.
Example: move_and_rename_module( "views/service_contractor_extra.py", "views/service_contractor/", new_name="extra" # or None for auto-detect ) Result: views/service_contractor/extra.py
Args: project_path: Root directory of the Python project module_path: Path to module file (relative to project_path) dest_folder: Destination folder path (relative to project_path) new_name: New name for the module (without .py), or None to auto-detect
Returns: JSON with success status and list of changed files
Inputs: project_path (required), module_path (required), dest_folder (required), new_name. Returns: result
move_moduleB
Move a module or package to another folder.
Updates all imports across the project automatically.
Args: project_path: Root directory of the Python project module_path: Path to module file or package folder (relative to project_path) dest_folder: Destination folder path (relative to project_path)
Returns: JSON with success status and list of changed files
Inputs: project_path (required), module_path (required), dest_folder (required). Returns: result
move_symbolA
Move a class or function to another file.
Updates all imports across the project automatically.
Args: project_path: Root directory of the Python project source_file: Source file path relative to project_path symbol_name: Name of the class or function to move dest_file: Destination file path (created if doesn't exist)
Returns: JSON with success status and list of changed files
Inputs: project_path (required), source_file (required), symbol_name (required), dest_file (required). Returns: result
rename_symbolA
Rename a symbol including all references and imports across the project.
Args: project_path: Root directory of the Python project file_path: File containing the symbol (relative to project_path) symbol_name: Current name of the symbol new_name: New name for the symbol
Returns: JSON with success status and list of changed files
Inputs: project_path (required), file_path (required), symbol_name (required), new_name (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: close project cleanup, two different module conversion strategies (to init vs to package), method extraction, variable inlining, symbol listing, module moving with optional rename, simple module moving, symbol moving, and symbol renaming. No two tools could be confused for the same operation.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., close_rope_project, convert_module_to_init, extract_method). Even multi-word verbs like move_and_rename_module are consistent, and no mixing of camelCase or other conventions occurs.
With 10 tools, the server is well-scoped for a Python refactoring assistant. Each tool addresses a specific refactoring or inspection task without unnecessary bloat or missing essential operations.
The tool set covers core refactorings (extract method, inline variable, rename symbol), module/package transformations, symbol movement, and project lifecycle (close). This provides a comprehensive surface for automated Python refactoring with no obvious dead ends.
Maintenance
Related MCP Connectors
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides TypeScript and JavaScript code refactoring operations using ts-morph, allowing AST-based symbol renaming, file/folder renaming, reference searching, and path alias removal when integrated with editor extensions like Cursor.826 npm17MIT
- AlicenseNot gradedqualityNot gradedmaintenanceA Model Context Protocol server that exposes Python Rope refactoring capabilities to Claude Code, enabling safe symbol renaming, method extraction, code analysis, and more.3MIT
- FlicenseAqualityDmaintenanceProvides code refactoring capabilities for TypeScript/JavaScript and Python through Language Server Protocol integration. Enables renaming symbols, extracting functions, finding references, and moving code between files via natural language commands.57-
- AlicenseNot gradedqualityDmaintenanceProvides tools for Python code navigation, analysis, and refactoring, including finding definitions, references, and symbol lists. It enables automated tasks such as renaming symbols and organizing imports to enhance AI-driven development.Apache 2.0