mcilspy 0.2.0

MCP Server for ILSpy .NET Decompiler

mcilspy

Decompile, search, and analyze .NET assemblies with AI assistance.

An MCP server that gives Claude (or any MCP client) the power to reverse-engineer .NET binaries — find hardcoded secrets, understand obfuscated code, recover lost source, and explore assembly internals.

---

Quick Start (30 seconds)

# Install
pip install mcilspy

# Add to Claude Code
claude mcp add ilspy -- python -m mcilspy.server

# Or add to Claude Desktop's config.json

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

That's it. Ask Claude to analyze any .dll or .exe:

"Decompile the LoginService class from this assembly and explain what it does"

---

What Can You Do?

Find Hardcoded Secrets

"Search for any URLs, API keys, or connection strings in MyApp.dll"

Discovers hardcoded credentials, endpoints, and configuration that shouldn't be in code.

Reverse Engineer Unknown Binaries

"List all the types in this DLL and identify the main entry points"

Understand the structure of any .NET assembly without source code.

Recover Lost Source Code

"Decompile the entire assembly to a project I can build"

Recreate compilable C# projects from binaries when source is unavailable.

Analyze Malware Behavior

"Find all network-related methods and show me what URLs this malware contacts"

Safe static analysis of suspicious .NET executables.

Understand Third-Party Libraries

"Show me how Newtonsoft.Json handles circular references"

Learn from decompiled implementations when documentation falls short.

---

Features at a Glance

Tool	What It Does	Requires ilspycmd?
decompile_assembly	Full C# source recovery	Yes
list_types	Enumerate classes, interfaces, enums	Yes
search_types	Find types by name pattern	Yes
search_strings	Find hardcoded strings (URLs, keys)	Yes
search_methods	Find methods by name	No
search_fields	Find fields and constants	No
search_properties	Find properties by name	No
list_events	List all events	No
list_resources	Find embedded files/images	No
get_metadata_summary	Assembly stats and references	No
generate_diagrammer	Interactive HTML type diagrams	Yes
get_assembly_info	Version, framework, signing info	Yes
check_ilspy_installation	Diagnose setup issues	No
install_ilspy	Auto-install .NET SDK + ilspycmd	No

6 tools work immediately (via dnfile) — no .NET SDK required. 8 more tools unlock with ilspycmd for full decompilation power.

---

Installation Options

Option 1: Just the MCP Server (metadata tools only)

pip install mcilspy

Gives you search and metadata tools immediately.

Option 2: Full Decompilation Power

# Install the MCP server
pip install mcilspy

# Let the server install ilspycmd for you (detects your OS automatically)
# Just ask Claude: "Install ilspycmd" or call install_ilspy with install_dotnet_sdk=true

Supported platforms for auto-install:

• Arch Linux (pacman)
• Ubuntu/Debian (apt)
• Fedora/RHEL (dnf)
• macOS (homebrew)
• Windows (winget / chocolatey)

Option 3: Manual ilspycmd Setup

# Install .NET SDK from https://dotnet.microsoft.com/download
# Then:
dotnet tool install --global ilspycmd

---

Table of Contents

• Quick Start
• What Can You Do?
• Features at a Glance
• Installation Options
• Tool Reference
  • Decompilation Tools
  • Metadata Tools
  • Installation Tools
• Configuration
• Troubleshooting
• License & Acknowledgments

---

Tool Reference

Decompilation Tools (requires ilspycmd)

decompile_assembly — Convert binaries back to C# source

The primary reverse-engineering tool. Decompiles .NET assemblies to readable C#.

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe
type_name	No	Specific type to decompile (e.g., MyNamespace.MyClass)
output_dir	No	Save decompiled files to directory
create_project	No	Generate compilable .csproj structure
language_version	No	C# version (default: Latest)
show_il_code	No	Output IL bytecode instead of C#

{
  "assembly_path": "/path/to/MyApp.dll",
  "type_name": "MyApp.Services.AuthService"
}

list_types — Enumerate types in an assembly

Your starting point for exploring unknown assemblies.

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe
entity_types	No	Filter: class, interface, struct, delegate, enum

{
  "assembly_path": "/path/to/MyApp.dll",
  "entity_types": ["class", "interface"]
}

search_types — Find types by name pattern

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe
pattern	Yes	Search pattern
namespace_filter	No	Limit to specific namespace
use_regex	No	Enable regex matching
case_sensitive	No	Case-sensitive search

{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "Controller",
  "namespace_filter": "MyApp.Web"
}

search_strings — Find hardcoded strings (secrets, URLs, config)

Essential for security analysis. Finds strings embedded in IL code.

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe
pattern	Yes	String to search for
use_regex	No	Enable regex matching
max_results	No	Limit results (default: 100)

{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "api\\..*\\.com"
  "use_regex": true
}

generate_diagrammer — Create interactive type relationship diagrams

Generates an HTML visualization of type hierarchies and relationships.

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe
output_dir	No	Where to save the HTML
include_pattern	No	Regex for types to include
exclude_pattern	No	Regex for types to exclude

get_assembly_info — Get assembly metadata

Returns version, target framework, strong name signing status, and debug info.

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe

Metadata Tools (no ilspycmd required)

These tools use direct PE/metadata parsing via dnfile and work without any .NET installation.

search_methods — Find methods by name pattern

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe
pattern	Yes	Method name pattern
type_filter	No	Limit to types containing this string
namespace_filter	No	Limit to specific namespace
public_only	No	Only public methods
use_regex	No	Enable regex matching

{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "Handle",
  "public_only": true
}

search_fields — Find fields and constants

Great for finding magic numbers, configuration values, and API keys stored as constants.

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe
pattern	Yes	Field name pattern
constants_only	No	Only literal/const fields
public_only	No	Only public fields

{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "Key|Secret|Password",
  "use_regex": true,
  "constants_only": true
}

search_properties — Find properties by name

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe
pattern	Yes	Property name pattern
type_filter	No	Limit to types containing this string
namespace_filter	No	Limit to specific namespace

list_events — List all events in an assembly

Useful for understanding event-driven architectures and observer patterns.

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe
type_filter	No	Limit to types containing this string
namespace_filter	No	Limit to specific namespace

list_resources — Find embedded resources

Discovers embedded files, images, localization data, and other resources.

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe

get_metadata_summary — Comprehensive assembly statistics

Returns type/method/field/property/event counts and referenced assemblies.

Parameter	Required	Description
assembly_path	Yes	Path to .dll or .exe

Installation & Diagnostics

check_ilspy_installation — Diagnose your setup

Shows whether dotnet CLI and ilspycmd are installed, with version info and troubleshooting tips.

No parameters required.

install_ilspy — Auto-install everything you need

Detects your platform and installs the .NET SDK and ilspycmd automatically.

Parameter	Required	Description
update	No	Update ilspycmd to latest version
install_dotnet_sdk	No	Also install .NET SDK if missing

{
  "install_dotnet_sdk": true
}

Auto-detected package managers: pacman, apt, dnf, zypper, homebrew, winget, chocolatey

---

Configuration

Environment Variables

Variable	Default	Description
LOGLEVEL	INFO	Logging verbosity: DEBUG, INFO, WARNING, ERROR

Debug Mode

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

---

Troubleshooting

"ilspycmd not found"

Ask Claude to run the installation tool:

"Install ilspycmd for me"

Or manually:

dotnet tool install --global ilspycmd
export PATH="$PATH:$HOME/.dotnet/tools"  # Add to your shell profile

"dotnet not installed"

The install_ilspy tool can install it automatically:

{"install_dotnet_sdk": true}

Or install manually from dotnet.microsoft.com/download

Assembly parsing errors

Some obfuscated or corrupted assemblies may fail to parse. The dnfile-based tools (search_methods, search_fields, etc.) are more tolerant than full decompilation.

---

Supported Formats

• .NET Framework assemblies (2.0 - 4.8)
• .NET Core / .NET 5-9+ assemblies
• Any PE file with .NET metadata

C# Language Versions: CSharp1 through CSharp12, Preview, Latest

---

License

MIT License — see LICENSE for details.

Acknowledgments

• Original project by Borealin — foundation for this MCP server
• ILSpy — the excellent open-source .NET decompiler
• dnfile — Python library for .NET metadata parsing
• Model Context Protocol — the integration standard

---

Built for security researchers, reverse engineers, and curious developers.