Skip to main content
Glama
rope-mcp-server

rope-mcp-server

by krystofbe

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.py into foo/__init__.py (no import changes!)

  • Convert Module to Package - Transform foo.py into foo/foo.py with import updates

  • Rename 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

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

From PyPI

pip install rope-mcp-server

Usage with Claude Code

claude mcp add rope-refactor uvx rope-mcp-server -s user
claude mcp list  # verify

That'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.py

move_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.py

move_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/lib

convert_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.py

Before:

app/views/customer_order.py
app/views/customer_order_mixins.py

After 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 prefix

Before:

app/views/customer_order/__init__.py
app/views/customer_order_mixins.py

Import: from app.views.customer_order_mixins import MyMixin

After:

app/views/customer_order/__init__.py
app/views/customer_order/mixins.py

Import: 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.py

Before:

app/views/service_contractor.py

Import: from app.views.service_contractor import MyClass

After:

app/views/service_contractor/
├── __init__.py
└── service_contractor.py

Import: 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_name

extract_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_helper

inline_variable

Inline a variable at all usage sites.

project_path: /path/to/your/project
file_path: src/handler.py
variable_name: temp_result
line: 42

close_rope_project

Close a Rope project to free memory. Call when done with refactoring.

project_path: /path/to/your/project

Development

# Install dependencies
uv sync

# Run tests
uv run pytest tests/ -v

# Run server locally
uv run python -m rope_mcp_server.server

How 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 tools
close_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:

  1. Move module to a temporary package (different name to trigger import updates)

  2. 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:

  1. Move module to destination folder

  2. 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

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A Model Context Protocol server that exposes Python Rope refactoring capabilities to Claude Code, enabling safe symbol renaming, method extraction, code analysis, and more.
      3
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Provides 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.
      5
      7
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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