# mcilspy

[![PyPI version](https://img.shields.io/pypi/v/mcilspy.svg)](https://pypi.org/project/mcilspy/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)

**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)

```bash
# Install
pip install mcilspy

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

# Or add to Claude Desktop's config.json
```

```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 (with PDB generation) | Yes |
| `decompile_method` | Extract a specific method from a type | Yes |
| `list_types` | Enumerate classes, interfaces, enums | Yes |
| `search_types` | Find types by name pattern | Yes |
| `search_strings` | Find hardcoded strings (URLs, keys) | No |
| `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 |
| `dump_package` | Extract assemblies from NuGet packages | Yes |
| `get_assembly_info` | Version, framework, signing info | Yes |
| `check_ilspy_installation` | Diagnose setup issues | No |
| `install_ilspy` | Auto-install .NET SDK + ilspycmd | No |

**7 tools work immediately** (via [dnfile](https://github.com/malwarefrank/dnfile)) — no .NET SDK required.
**9 more tools** unlock with `ilspycmd` for full decompilation power.

---

## Installation Options

### Option 1: Just the MCP Server (metadata tools only)
```bash
pip install mcilspy
```
Gives you search and metadata tools immediately.

### Option 2: Full Decompilation Power
```bash
# 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
```bash
# Install .NET SDK from https://dotnet.microsoft.com/download
# Then:
dotnet tool install --global ilspycmd
```

---

## Table of Contents

- [Quick Start](#quick-start-30-seconds)
- [What Can You Do?](#what-can-you-do)
- [Features at a Glance](#features-at-a-glance)
- [Installation Options](#installation-options)
- [Tool Reference](#tool-reference)
  - [Decompilation & Extraction Tools](#decompilation-tools-requires-ilspycmd)
  - [Metadata Tools](#metadata-tools-no-ilspycmd-required)
  - [Installation Tools](#installation--diagnostics)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
- [License & Acknowledgments](#license)

---

## Tool Reference

### Decompilation Tools (requires ilspycmd)

<details>
<summary><strong>decompile_assembly</strong> — Convert binaries back to C# source</summary>

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# |
| `generate_pdb` | No | Generate portable PDB for debugging (requires `output_dir`) |
| `use_pdb_variable_names` | No | Use original variable names from existing PDB |

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "type_name": "MyApp.Services.AuthService",
  "use_pdb_variable_names": true
}
```
</details>

<details>
<summary><strong>decompile_method</strong> — Extract a specific method from a type</summary>

When a type is too large to return in full, use this to extract just the method you need.
Decompiles the containing type, then extracts the named method. IL mode (default) is most reliable.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |
| `type_name` | Yes | Fully qualified type (e.g., `MyNamespace.MyClass`) |
| `method_name` | Yes | Method to extract (all overloads returned) |
| `show_il_code` | No | Output IL instead of C# (default: true) |
| `language_version` | No | C# version (default: Latest) |
| `use_pdb_variable_names` | No | Use original variable names from PDB |

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "type_name": "MyApp.Core.CyBGElaborator",
  "method_name": "DoElaborate"
}
```
</details>

<details>
<summary><strong>list_types</strong> — Enumerate types in an assembly</summary>

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` |

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "entity_types": ["class", "interface"]
}
```
</details>

<details>
<summary><strong>search_types</strong> — Find types by name pattern</summary>

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

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "Controller",
  "namespace_filter": "MyApp.Web"
}
```
</details>

<details>
<summary><strong>search_strings</strong> — Find hardcoded strings (secrets, URLs, config)</summary>

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) |

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "api\\..*\\.com"
  "use_regex": true
}
```
</details>

<details>
<summary><strong>generate_diagrammer</strong> — Create interactive type relationship diagrams</summary>

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 |

</details>

<details>
<summary><strong>dump_package</strong> — Extract assemblies from NuGet packages</summary>

Extracts all assemblies from a NuGet package folder structure into a flat directory for bulk analysis.

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to assembly or NuGet package folder |
| `output_dir` | Yes | Directory to dump assemblies into |

```json
{
  "assembly_path": "/path/to/packages/Newtonsoft.Json",
  "output_dir": "./extracted-assemblies"
}
```

Useful for analyzing package dependencies or bulk decompilation of NuGet packages.
</details>

<details>
<summary><strong>get_assembly_info</strong> — Get assembly metadata</summary>

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

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |

</details>

### Metadata Tools (no ilspycmd required)

These tools use direct PE/metadata parsing via [dnfile](https://github.com/malwarefrank/dnfile) and work without any .NET installation.

<details>
<summary><strong>search_methods</strong> — Find methods by name pattern</summary>

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

```json
{
  "assembly_path": "/path/to/MyApp.dll",
  "pattern": "Handle",
  "public_only": true
}
```
</details>

<details>
<summary><strong>search_fields</strong> — Find fields and constants</summary>

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 |

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

<details>
<summary><strong>search_properties</strong> — Find properties by name</summary>

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

</details>

<details>
<summary><strong>list_events</strong> — List all events in an assembly</summary>

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 |

</details>

<details>
<summary><strong>list_resources</strong> — Find embedded resources</summary>

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

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |

</details>

<details>
<summary><strong>get_metadata_summary</strong> — Comprehensive assembly statistics</summary>

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

| Parameter | Required | Description |
|-----------|:--------:|-------------|
| `assembly_path` | Yes | Path to .dll or .exe |

</details>

### Installation & Diagnostics

<details>
<summary><strong>check_ilspy_installation</strong> — Diagnose your setup</summary>

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

No parameters required.
</details>

<details>
<summary><strong>install_ilspy</strong> — Auto-install everything you need</summary>

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 |

```json
{
  "install_dotnet_sdk": true
}
```

**Auto-detected package managers:** pacman, apt, dnf, zypper, homebrew, winget, chocolatey
</details>

---

## Configuration

### Environment Variables

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

### Debug Mode

```json
{
  "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:
```bash
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:
```json
{"install_dotnet_sdk": true}
```

Or install manually from [dotnet.microsoft.com/download](https://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](LICENSE) for details.

## Acknowledgments

- **Original project by [Borealin](https://github.com/Borealin/ilspy-mcp-server)** — foundation for this MCP server
- **[ILSpy](https://github.com/icsharpcode/ILSpy)** — the excellent open-source .NET decompiler
- **[dnfile](https://github.com/malwarefrank/dnfile)** — Python library for .NET metadata parsing
- **[Model Context Protocol](https://modelcontextprotocol.io/)** — the integration standard

---

<p align="center">
  <i>Built for security researchers, reverse engineers, and curious developers.</i>
</p>