mcilspy

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

Features

ILSpy-based Tools (requires ilspycmd)

• Decompile Assemblies: Convert .NET assemblies back to readable C# source code
• List Types: Enumerate classes, interfaces, structs, delegates, and enums in assemblies
• Search Types: Find types by name pattern with regex support
• Search Strings: Find hardcoded strings in assembly code (URLs, credentials, etc.)
• Generate Diagrammer: Create interactive HTML visualizations of assembly structure
• Assembly Information: Get metadata about .NET assemblies (version, target framework, etc.)

Direct Metadata Tools (no ilspycmd required)

• Search Methods: Find methods by name pattern directly from metadata tables
• Search Fields: Find fields and constants in assemblies
• Search Properties: Find properties by name pattern
• List Events: Enumerate all events defined in an assembly
• List Resources: List embedded resources (files, images, etc.)
• Metadata Summary: Get comprehensive assembly metadata with statistics

Installation & Diagnostics

• Check Installation: Verify ilspycmd and dotnet CLI status
• Install ILSpy: Automatically install or update ilspycmd

Prerequisites

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

   dotnet tool install --global ilspycmd
   

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

Installation

Install from PyPI:

pip install mcilspy

Or for development:

git clone https://github.com/Borealin/mcilspy.git
cd mcilspy
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", "mcilspy.server"]
    }
  }
}

Available Tools

1. decompile_assembly

Decompile a .NET assembly to C# source code. This is the primary tool for reverse-engineering .NET binaries.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• output_dir (optional): Output directory for decompiled files
• type_name (optional): Fully qualified type name to decompile (e.g., "MyNamespace.MyClass")
• language_version (optional): C# language version (default: "Latest")
• create_project (optional): Create a compilable project structure
• show_il_code (optional): Show IL bytecode instead of C#
• remove_dead_code (optional): Remove unreachable code during decompilation
• remove_dead_stores (optional): Remove unused variable assignments
• show_il_sequence_points (optional): Include debugging sequence points in IL output
• 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. Typically the first tool to use when analyzing an unknown assembly.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• entity_types (optional): Types to include (accepts full names or single letters):
  • "class" or "c" (default)
  • "interface" or "i"
  • "struct" or "s"
  • "delegate" or "d"
  • "enum" or "e"

Example:

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

3. search_types

Search for types by name pattern. Essential for finding specific classes in large assemblies.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• pattern (required): Search pattern to match against type names
• namespace_filter (optional): Only search in namespaces containing this string
• entity_types (optional): Types to search (default: all types)
• case_sensitive (optional): Case-sensitive matching (default: false)
• use_regex (optional): Treat pattern as regular expression (default: false)

Example:

{
  "name": "search_types",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "pattern": "Service",
    "namespace_filter": "MyApp.Services"
  }
}

4. search_strings

Search for string literals in assembly code. Crucial for reverse engineering - finds hardcoded URLs, credentials, configuration, etc.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• pattern (required): String pattern to search for
• case_sensitive (optional): Case-sensitive matching (default: false)
• use_regex (optional): Treat pattern as regular expression (default: false)
• max_results (optional): Maximum matches to return (default: 100)

Example:

{
  "name": "search_strings",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "pattern": "api.example.com"
  }
}

5. generate_diagrammer

Generate an interactive HTML diagram showing assembly type relationships.

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

6. get_assembly_info

Get metadata and version information about an assembly.

Parameters:

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

Returns: Assembly name, version, target framework, signing status, and debug info availability.

Direct Metadata Tools

These tools use direct PE/metadata parsing via dnfile and don't require ilspycmd to be installed.

7. search_methods

Search for methods in an assembly by name pattern. Useful for finding entry points, event handlers, and API endpoints.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• pattern (required): Search pattern to match against method names
• type_filter (optional): Only search methods in types containing this string
• namespace_filter (optional): Only search in namespaces containing this string
• public_only (optional): Only return public methods (default: false)
• case_sensitive (optional): Case-sensitive matching (default: false)
• use_regex (optional): Treat pattern as regular expression (default: false)

Example:

{
  "name": "search_methods",
  "arguments": {
    "assembly_path": "/path/to/MyAssembly.dll",
    "pattern": "Handle",
    "public_only": true
  }
}

8. search_fields

Search for fields and constants in an assembly. Useful for finding configuration values and magic numbers.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• pattern (required): Search pattern to match against field names
• type_filter (optional): Only search fields in types containing this string
• namespace_filter (optional): Only search in namespaces containing this string
• public_only (optional): Only return public fields (default: false)
• constants_only (optional): Only return constant (literal) fields (default: false)
• case_sensitive (optional): Case-sensitive matching (default: false)
• use_regex (optional): Treat pattern as regular expression (default: false)

9. search_properties

Search for properties in an assembly by name pattern. Useful for finding data model fields and configuration properties.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• pattern (required): Search pattern to match against property names
• type_filter (optional): Only search properties in types containing this string
• namespace_filter (optional): Only search in namespaces containing this string
• case_sensitive (optional): Case-sensitive matching (default: false)
• use_regex (optional): Treat pattern as regular expression (default: false)

10. list_events

List all events defined in an assembly. Useful for understanding event-driven architecture and observer patterns.

Parameters:

• assembly_path (required): Path to the .NET assembly file
• type_filter (optional): Only list events in types containing this string
• namespace_filter (optional): Only list events in namespaces containing this string

11. list_resources

List all embedded resources in an assembly. Finds embedded files, images, localization data, etc.

Parameters:

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

12. get_metadata_summary

Get a comprehensive metadata summary with statistics. More accurate than get_assembly_info for metadata counts.

Parameters:

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

Returns: Assembly identity, type/method/field/property/event/resource counts, and referenced assemblies.

Installation & Diagnostics Tools

13. check_ilspy_installation

Check if ilspycmd and dotnet CLI are installed and working. Use this to diagnose issues.

Parameters: None

Returns: Installation status with version information and troubleshooting tips.

14. install_ilspy

Install or update ilspycmd automatically. Detects your platform and package manager for optimal installation experience.

Parameters:

• update (optional): If true, update to the latest version even if already installed (default: false)
• install_dotnet_sdk (optional): If true, attempt to install .NET SDK when missing (default: false). Supports automatic detection for:
  • Arch Linux: pacman
  • Ubuntu/Debian: apt
  • Fedora/RHEL: dnf
  • openSUSE: zypper
  • macOS: homebrew
  • Windows: winget or chocolatey

Example - Update ilspycmd:

{
  "name": "install_ilspy",
  "arguments": {
    "update": true
  }
}

Example - Full installation (SDK + ilspycmd):

{
  "name": "install_ilspy",
  "arguments": {
    "install_dotnet_sdk": true
  }
}

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 mcilspy
   

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

   {
     "mcpServers": {
       "ilspy": {
         "command": "python",
         "args": ["-m", "mcilspy.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", "mcilspy.server"],
      "env": {
        "LOGLEVEL": "INFO"
      }
    }
  }
}

Development/Testing:

{
  "mcpServers": {
    "ilspy": {
      "command": "python",
      "args": ["-m", "mcilspy.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

• Original project by Borealin - Thank you for creating the foundation for this MCP server!
• Built on top of the excellent ILSpy decompiler
• Uses the Model Context Protocol for integration