RePythonNET-MCP

An MCP (Model Context Protocol) server for static analysis and patching of .NET binaries.

Uses dnlib for IL parsing and editing, and the ILSpy/dnSpy decompiler engine for C# source reconstruction. Exposes 38 tools over a standard MCP interface, making it easy to integrate with any MCP-compatible LLM agent.

Designed to run as a standalone Docker container, and also ships with integration files for SARA — an internal automated malware reverse engineering system developed at Sekoia.io.

Features

Decompile any .NET class or method to readable C#
Enumerate types, methods, fields, imports, resources, entry point
Analyse IL opcodes, call graphs, callers, string literals
Detect P/Invoke declarations, reflection usage, large byte arrays
Rename obfuscated classes, methods, and fields (in-memory, non-destructive)
Patch IL instructions: replace strings, NOP out instructions, bypass checks, invert branches, patch static fields
Save the modified binary to disk
Upload binaries via HTTP, or load directly from a URL
Multi-session: analyse several binaries in parallel with separate analysis_id identifiers

Architecture

┌─────────────────────────────────┐
│  Any MCP client / LLM agent     │
│  (curl, Python, SARA, etc.)     │
└──────────────┬──────────────────┘
               │  JSON-RPC over HTTP
               ▼
┌─────────────────────────────────┐
│  pythonnet-mcp  (port 8001)     │
│                                 │
│  server.py                      │
│  ├── FastMCP (38 tools)         │
│  ├── POST /upload               │
│  └── GET  /download             │
│                                 │
│  Runtime: Python + Mono         │
│  .NET libs: dnlib, ILSpy/dnSpy  │
└─────────────────────────────────┘

The server is stateless across requests but holds in-memory sessions keyed by analysis_id. Each session stores the loaded dnlib module and a lazily-initialised ILSpy decompiler instance.

Quick Start

Docker (recommended)

# Create the required directories (first time only)
mkdir -p data/samples data/pythonnet_projects logs

# Build and run
docker compose -f docker-compose.yml up --build

# The server listens on http://localhost:8001

Direct (without Docker)

Prerequisites: Python 3.11+, mono-complete, and the .NET assemblies in dll/.

pip install -r requirements.txt

# Override default paths to avoid needing write access to /data/
export PYTHONNET_PROJECTS_DIR=./data/pythonnet_projects
export SAMPLES_DIR=./data/samples
mkdir -p data/pythonnet_projects data/samples

python server.py --host 0.0.0.0 --port 8001

CLI options:

Option	Default	Description
`--host`	`0.0.0.0`	Bind address
`--port`	`8001`	Bind port
`--binary`	(none)	Optional binary to pre-load at startup

Claude Desktop Configuration

The file scripts/wrapper.py is a wrapper to put on your host. Then configure Claude Desktop (claude_desktop_config.json) to execute this file.

{
  "mcpServers": {
    "pythonnet": {
      "command": "<path to python>",
      "args": [
        "<path to wrapper.py>"
      ]
    }
  },
}

Usage

Upload a binary

You first needs to upload the file using the /upload endpoint:

curl -F file=@malware.dll http://localhost:8001/upload
# {"path": "/data/pythonnet_projects/_uploads/malware.dll", "size_bytes": 45056}

You can then ask Claude Desktop to use this MCP service to load and analyze the binary. You can use pythonnet_list_uploaded_files to list already uploaded files.

Call an MCP tool (raw JSON-RPC)

curl -s -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "pythonnet_load_binary",
      "arguments": {
        "binary_path": "/data/pythonnet_projects/_uploads/malware.dll",
        "analysis_id": "session1"
      }
    }
  }'

Session isolation: append ?session_id=<value> to the URL to keep sessions independent when running parallel analyses from multiple clients.

List available tools

curl -s -X POST http://localhost:8001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Download a file

# Download a patched binary produced by pythonnet_save_binary
curl "http://localhost:8001/download?path=/data/pythonnet_projects/session1/malware_patched.dll" \
  -o malware_patched.dll

Downloads are restricted to files inside /data/pythonnet_projects/ and /data/samples/.

Tools Reference

All tool names are prefixed with pythonnet_. The analysis_id parameter defaults to "default" and identifies the session.

Loading

Tool	Key Parameters	Description
`pythonnet_load_binary`	`binary_path`, `analysis_id`	Load a .NET binary from disk. Copies it to a project directory before opening so the original is never modified.
`pythonnet_load_from_url`	`url`, `analysis_id`	Download a .NET binary from HTTP/HTTPS and load it.
`pythonnet_unload_binary`	`analysis_id`	Unload a binary and free its memory.
`pythonnet_list_uploaded_files`	`extension`	List binaries in the upload staging area and the samples directory.
`pythonnet_list_active_sessions`	—	List all active and on-disk analysis sessions.

Enumeration

Tool	Key Parameters	Description
`pythonnet_list_all_classes`	`analysis_id`, `namespace_filter`	List all types defined in the binary.
`pythonnet_list_all_methods`	`analysis_id`, `class_filter`	List all methods that have a body.
`pythonnet_list_all_methods_inside_class`	`class_name`, `analysis_id`	List all methods (including abstract/interface) inside a specific class.

Decompilation

Tool	Key Parameters	Description
`pythonnet_decompile_class`	`class_name`, `analysis_id`	Decompile an entire class to C# source.
`pythonnet_decompile_method`	`class_name`, `method_name`, `analysis_id`, `method_index`	Decompile a single method. Use `method_index` to disambiguate overloads.
`pythonnet_decompile_all_classes`	`analysis_id`	Decompile every class in the binary at once.

Metadata

Tool	Key Parameters	Description
`pythonnet_get_module_info`	`analysis_id`	Assembly name, version, culture, runtime version, target framework.
`pythonnet_get_entry_point`	`analysis_id`	Managed entry point (`Main` or `EntryPoint` metadata).
`pythonnet_get_imports`	`analysis_id`	All external assemblies and types referenced by the binary.
`pythonnet_get_fields`	`class_name`, `analysis_id`	All fields of a class with their types and visibility.
`pythonnet_get_custom_attributes`	`class_name`, `analysis_id`, `method_name`	Custom attributes on a class or one of its methods.
`pythonnet_get_resources`	`analysis_id`	List all embedded resources.
`pythonnet_extract_resource`	`resource_name`, `analysis_id`	Extract a raw embedded resource to a file.

IL Analysis

Tool	Key Parameters	Description
`pythonnet_get_opcodes`	`class_name`, `method_name`, `analysis_id`, `method_index`	Dump the raw IL instruction listing of a method.
`pythonnet_get_method_calls`	`class_name`, `method_name`, `analysis_id`, `method_index`	List all outgoing `call`/`callvirt` instructions from a method.
`pythonnet_get_callers`	`class_name`, `method_name`, `analysis_id`	Find all methods that call a given method (reverse call graph).
`pythonnet_get_call_graph`	`class_name`, `method_name`, `analysis_id`, `max_depth`	BFS call graph from a root method (default max depth: 5, internal calls only).
`pythonnet_find_dead_code`	`analysis_id`	Find methods that are never called from within the binary.

String and Name Search

Tool	Key Parameters	Description
`pythonnet_get_strings`	`analysis_id`, `min_length`	List all unique `ldstr` string literals across all method bodies.
`pythonnet_search_string`	`search_string`, `analysis_id`	Find all methods that reference a given string literal.
`pythonnet_search_method_by_name`	`method_name`, `analysis_id`	Search for methods by partial name match across all classes.

Behavioral Indicators

Tool	Key Parameters	Description
`pythonnet_find_pinvoke`	`analysis_id`, `dll_filter`	List all P/Invoke (`DllImport`) declarations.
`pythonnet_find_reflection_calls`	`analysis_id`	Find all uses of `System.Reflection` (Assembly.Load, GetMethod, Invoke, etc.).
`pythonnet_find_large_byte_arrays`	`analysis_id`, `min_size`	Find methods that allocate large byte arrays (potential payload buffers; default min: 256 bytes).

Renaming (Deobfuscation)

Changes are in-memory only. Call pythonnet_save_binary to persist.

Tool	Key Parameters	Description
`pythonnet_rename_class`	`class_name`, `new_name`, `analysis_id`, `new_namespace`	Rename a class and optionally its namespace.
`pythonnet_rename_method`	`class_name`, `method_name`, `new_method_name`, `analysis_id`, `method_index`	Rename a method.
`pythonnet_rename_field`	`class_name`, `field_name`, `new_field_name`, `analysis_id`	Rename a field.

IL Patching

Changes are in-memory only. Call pythonnet_save_binary to persist.

Tool	Key Parameters	Description
`pythonnet_patch_ldstr`	`class_name`, `method_name`, `il_offset`, `new_string`, `analysis_id`	Replace the string operand of an `ldstr` instruction at a given IL offset.
`pythonnet_nop_instructions`	`class_name`, `method_name`, `il_offsets`, `analysis_id`	Replace one or more instructions with `nop`.
`pythonnet_patch_return`	`class_name`, `method_name`, `return_value`, `analysis_id`	Replace a method body with a minimal return (useful to bypass a check).
`pythonnet_patch_branch`	`class_name`, `method_name`, `il_offset`, `mode`, `analysis_id`	Flip (`invert`), force (`always`/`never`), or NOP a conditional branch.
`pythonnet_set_field_constant`	`class_name`, `field_name`, `new_value`, `analysis_id`	Patch the initialization value of a static field in `.cctor`.
`pythonnet_save_binary`	`analysis_id`, `output_path`	Write the modified module to disk.

Volumes and Paths

Path (in container)	Purpose	Notes
`/data/samples/`	Read-only input samples	Mount your binary directory here
`/data/pythonnet_projects/`	Per-session working directories	Created automatically; writable
`/data/pythonnet_projects/_uploads/`	HTTP upload staging area	Used by the `/upload` endpoint

When running standalone, adjust the volume mounts in docker-compose.yml to your local directory layout.

Configuration

Environment Variable	Default	Description
`WEB_SERVER_PORT`	`8001`	Port the server binds to
`PYTHONNET_PROJECTS_DIR`	`/data/pythonnet_projects`	Working directory for analysis sessions (uploads, patched binaries, extracted resources)
`SAMPLES_DIR`	`/data/samples`	Read-only input directory scanned by `pythonnet_list_uploaded_files`

Dependencies

Python packages (see requirements.txt):

pythonnet ≥ 3.0 — Python/.NET CLR interop
fastmcp — MCP server framework
mcp ≥ 1.0 — MCP SDK
click, requests, aiofiles

System (installed in the Docker image): mono-complete

.NET assemblies (bundled in dll/):

Assembly	License	Source
`dnlib.dll`	MIT	0xd4d/dnlib
`ICSharpCode.Decompiler.dll`	MIT	icsharpcode/ILSpy
`ICSharpCode.NRefactory*.dll`	MIT	ILSpy / NRefactory
`dnSpy.Decompiler*.dll`	GPL-3.0	dnSpy/dnSpy
`dnSpy.Contracts.Logic.dll`	GPL-3.0	dnSpy/dnSpy

License note: The dnSpy assemblies are GPL-3.0. If you distribute a modified version of this project that includes those files, the GPL-3.0 terms apply to the distribution. Using the service as-is (running the Docker container) is not affected.

SARA Integration

SARA is an internal automated malware reverse engineering system developed at Sekoia.io. It uses this service as its .NET analysis backend. Two additional files support that integration:

`tools.py` — MCP client

A lightweight HTTP client that runs inside the SARA process and proxies tool calls to this server. It:

Auto-detects whether it is running inside Docker (uses http://pythonnet-mcp:8001/mcp) or on the host (uses http://localhost:8001/mcp), and respects the PYTHONNET_MCP_URL environment variable.
Fetches tool definitions from the server at runtime (tools/list) with a 5-minute cache — the server is the single source of truth for schemas.
Normalises legacy relative paths (data/samples/file.dll → /data/samples/file.dll) before forwarding requests.
Exposes PythonnetToolRegistry, the class that SARA's service registry instantiates per analysis run.

from services.pythonnet.tools import PythonnetToolRegistry

registry = PythonnetToolRegistry(session_id="sara-abc12")
result = registry.execute_tool("pythonnet_list_all_classes", {"analysis_id": "sara-abc12"})

`policy.py` — Tool usage policy

Controls tool call limits and deduplication inside SARA's LangGraph analysis loop. Not needed outside SARA.

Tool	Limit
`pythonnet_load_binary`	1 per session
`pythonnet_list_all_classes`	3 + lock_clears
`pythonnet_list_all_methods`	3 + lock_clears
`pythonnet_list_all_methods_inside_class`	20 + (lock_clears × 5)
`pythonnet_decompile_class`	50 + (lock_clears × 10)
`pythonnet_decompile_method`	unlimited
`pythonnet_rename_class`	20 + lock_clears
`pythonnet_rename_method`	50 + (lock_clears × 10)

lock_clears is incremented by SARA's loop when it detects the LLM is stuck, progressively relaxing limits.

Registration in SARA

In core/services_registry.py:

def _make_pythonnet_toolset(session_id: str):
    from services.pythonnet.tools import PythonnetToolRegistry
    return PythonnetToolRegistry(session_id=session_id)

SERVICE_FACTORIES["pythonnet"] = _make_pythonnet_toolset

PIPELINES["pythonnet"] = {
    "name": "Pythonnet",
    "description": ".NET assembly decompilation and patching",
    "supported_formats": ["EXE", "DLL", ".NET"],
    "capabilities": ["decompile", "patch", "rename"],
    "services": ["pythonnet"],
    "available": _pythonnet_available,
    "loader_tool": "pythonnet_load_binary",
}

Volume layout in SARA

When running inside SARA's docker-compose-sara-dev.yml:

/data/samples is mounted read-only in the pythonnet-mcp container. The server never writes there.
All write operations (working copies, patched binaries, extracted resources) go to /data/pythonnet_projects/{analysis_id}/.

License

The Python source files in this project are released under the MIT License — see LICENSE.

The bundled .NET assemblies in dll/ are subject to their own licenses — see the Dependencies section above, in particular the GPL-3.0 notice for the dnSpy assemblies.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
dll		dll
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
docker-compose.yml		docker-compose.yml
policy.py		policy.py
pythonnet-mcp.dockerfile		pythonnet-mcp.dockerfile
requirements.txt		requirements.txt
server.py		server.py
start.sh		start.sh
tools.py		tools.py

Folders and files

Latest commit

History

Repository files navigation

RePythonNET-MCP

Features

Architecture

Quick Start

Docker (recommended)

Direct (without Docker)

Claude Desktop Configuration

Usage

Upload a binary

Call an MCP tool (raw JSON-RPC)

List available tools

Download a file

Tools Reference

Loading

Enumeration

Decompilation

Metadata

IL Analysis

String and Name Search

Behavioral Indicators

Renaming (Deobfuscation)

IL Patching

Volumes and Paths

Configuration

Dependencies

SARA Integration

tools.py — MCP client

policy.py — Tool usage policy

Registration in SARA

Volume layout in SARA

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`tools.py` — MCP client

`policy.py` — Tool usage policy

Packages