Borealin/ilspy-mcp-server

ILSpy MCP Server

A Model Context Protocol (MCP) server that provides .NET assembly decompilation capabilities using ILSpy.

Features

• Decompile Assemblies: Convert .NET assemblies back to readable C# source code
• List Types: Enumerate classes, interfaces, structs, delegates, and enums in assemblies
• Generate Diagrammer: Create interactive HTML visualizations of assembly structure
• Assembly Information: Get metadata about .NET assemblies

Prerequisites

1. ILSpy Command Line Tool: Install the global dotnet tool:

   dotnet tool install --global ilspycmd
   

2. Python 3.8+: Required for running the MCP server

Installation

Install from PyPI:

pip install ilspy-mcp-server

Or for development:

git clone https://github.com/Borealin/ilspy-mcp-server.git
cd ilspy-mcp-server
pip install -e .

Usage

MCP Client Configuration

Configure your MCP client (e.g., Claude Desktop) to use the server:

{
  "mcpServers": {
    "ilspy": {
      "command": "python",
      "args": ["-m", "ilspy_mcp_server.server"]
    }
  }
}

Available Tools

1. decompile_assembly

Decompile a .NET assembly to C# source code.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• output_dir (optional): Output directory for decompiled files
• type_name (optional): Specific type to decompile
• language_version (optional): C# language version (default: "Latest")
• create_project (optional): Create a compilable project structure
• show_il_code (optional): Show IL code instead of C#
• remove_dead_code (optional): Remove dead code during decompilation
• nested_directories (optional): Use nested directories for namespaces

Example:

{
  "name": "decompile_assembly",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "type_name": "MyNamespace.MyClass",
    "language_version": "CSharp10_0"
  }
}

2. list_types

List types in a .NET assembly.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• entity_types (optional): Array of entity types to list ("c", "i", "s", "d", "e")

Example:

{
  "name": "list_types",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "entity_types": ["c", "i"]
  }
}

3. generate_diagrammer

Generate an interactive HTML diagrammer.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• output_dir (optional): Output directory for the diagrammer
• include_pattern (optional): Regex pattern for types to include
• exclude_pattern (optional): Regex pattern for types to exclude

4. get_assembly_info

Get basic information about an assembly.

Parameters:

• assembly_path (required): Path to the .NET assembly file

Available Prompts

1. analyze_assembly

Analyze a .NET assembly and provide insights about its structure.

2. decompile_and_explain

Decompile a specific type and provide explanation of its functionality.

Supported Assembly Types

• .NET Framework assemblies (.dll, .exe)
• .NET Core/.NET 5+ assemblies
• Portable Executable (PE) files with .NET metadata

Supported C# Language Versions

• CSharp1 through CSharp12_0
• Preview
• Latest (default)

Quick Start

1. Install the package:

   pip install ilspy-mcp-server
   

2. Configure your MCP client (Claude Desktop example):

   {
     "mcpServers": {
       "ilspy": {
         "command": "python",
         "args": ["-m", "ilspy_mcp_server.server"]
       }
     }
   }
   

3. Use the tools in your MCP client:

   • Ask to decompile a .NET assembly
   • List types in an assembly
   • Generate interactive diagrams
   • Get assembly information

Error Handling

The server provides detailed error messages for common issues:

• Assembly file not found
• Invalid assembly format
• ILSpyCmd not installed or not in PATH
• Permission issues
• Decompilation failures

Configuration

Environment Variables

• LOGLEVEL: Set logging level (DEBUG, INFO, WARNING, ERROR). Default: INFO

MCP Client Examples

Claude Desktop (config.json):

{
  "mcpServers": {
    "ilspy": {
      "command": "python",
      "args": ["-m", "ilspy_mcp_server.server"],
      "env": {
        "LOGLEVEL": "INFO"
      }
    }
  }
}

Development/Testing:

{
  "mcpServers": {
    "ilspy": {
      "command": "python",
      "args": ["-m", "ilspy_mcp_server.server"],
      "env": {
        "LOGLEVEL": "DEBUG"
      }
    }
  }
}

Troubleshooting

Common Issues

1. "ILSpyCmd not found":

   dotnet tool install --global ilspycmd
   

2. "Assembly file not found":

   • Check the file path is correct
   • Ensure the file has .dll or .exe extension

3. Permission errors:

   • Ensure read access to assembly files
   • Check output directory permissions

Debug Mode

Enable debug logging to see detailed operation info:

{
  "env": {
    "LOGLEVEL": "DEBUG"
  }
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built on top of the excellent ILSpy decompiler
• Uses the Model Context Protocol for integration