RoslynMcp.Core 0.4.0

Roslyn MCP Server

Let AI assistants like Claude safely refactor your C# codebase using the same Roslyn compiler platform that powers Visual Studio.

Roslyn MCP Server is a Model Context Protocol (MCP) server that exposes 41 Roslyn-powered tools to AI assistants and other MCP clients. It combines 19 refactoring operations, 5 code navigation tools, 6 analysis and metrics tools, 4 code generation tools, and 7 code conversion tools -- giving your AI deep code intelligence, comprehensive refactoring, and modern C# syntax transformations with full solution-wide reference tracking and preview support.

Table of Contents

• Why RoslynMcpServer?
• Prerequisites
• Quick Start
• Standalone CLI
• Configuration
• Available Tools
• Preview Mode
• Troubleshooting
• NuGet Libraries
• Contributing
• License

Why RoslynMcpServer?

• 41 tools -- refactoring, navigation, analysis, generation, and conversion tools, the most comprehensive Roslyn MCP server available
• Preview mode on every operation -- see exactly what will change before applying
• Atomic file writes with rollback -- if any file write fails, all changes are reverted
• Solution-wide reference updates -- renames and moves propagate across your entire solution
• Single command install -- dotnet tool install -g RoslynMcp.Server, no repo cloning needed
• Cross-platform -- works on Windows, Linux, and macOS

Prerequisites

Before installing, make sure you have:

1. .NET 9.0 SDK or later -- Download here
2. A C# solution (.sln or .slnx) or project (.csproj) to work with

Verify your .NET SDK version:

dotnet --version

The output should be 9.0.x or higher.

Quick Start

1. Install

dotnet tool install -g RoslynMcp.Server

2. Configure

Create a .mcp.json file in your project root (for Claude Code):

{
  "mcpServers": {
    "roslyn-refactor": {
      "type": "stdio",
      "command": "roslyn-mcp",
      "args": []
    }
  }
}

Then restart Claude Code or run /mcp to connect.

3. Verify

Ask Claude:

"Run the roslyn diagnose tool for my solution at C:/path/to/MySolution.sln"

You should see a health report with Roslyn version, MSBuild status, and workspace details.

4. Try It

Ask Claude:

"Rename the class UserService to AccountService in C:/path/to/MySolution.sln"

Claude will use the rename_symbol tool to rename the class and update every reference across your entire solution.

Standalone CLI

All 41 tools are also available as a standalone CLI for use in scripts, CI/CD pipelines, and terminals without an AI assistant.

Install

dotnet tool install -g RoslynMcp.Cli

Usage

roslyn-cli <solution-path> <tool-name> [--option value ...]
roslyn-cli <tool-name> --help
roslyn-cli --help

Examples

# Check environment health
roslyn-cli C:/path/to/MySolution.sln diagnose --format text

# Rename a symbol across the entire solution
roslyn-cli C:/path/to/MySolution.sln rename-symbol --source-file C:/path/to/Foo.cs --symbol-name Bar --new-name Baz

# Get compiler diagnostics (errors only), pipe to jq
roslyn-cli C:/path/to/MySolution.sln get-diagnostics --severity-filter Error | jq '.data'

# Preview a refactoring without applying
roslyn-cli C:/path/to/MySolution.sln extract-method --source-file Foo.cs --start-line 10 --end-line 20 --method-name DoWork --preview

Output is JSON by default (pipeable to jq). Use --format text for human-readable output. Exit codes: 0=success, 1=tool error, 2=CLI error, 3=environment error.

Configuration

Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "roslyn-refactor": {
      "type": "stdio",
      "command": "roslyn-mcp",
      "args": []
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "roslyn-refactor": {
      "command": "roslyn-mcp",
      "args": []
    }
  }
}

Config file locations:

Available Tools

All tools accept a solutionPath parameter (absolute path to a .sln, .slnx, or .csproj file). Refactoring tools also accept a preview parameter (set to true to see changes without applying them).

Move and Rename

Extract

Inline

Signature and Encapsulation

Generate

Convert

Using Directives

Diagnostics

Code Navigation

These read-only tools let you explore and understand your codebase without making changes. Use them to discover symbols, trace references, and inspect type information before refactoring.

Analysis & Metrics

These tools analyze your code without making changes. Use them to understand code quality, data flow, and control flow.

Code Generation

These tools generate new code members for existing types.

Preview Mode

Every refactoring tool supports a preview parameter. When set to true, the tool computes and returns the changes that would be made without writing anything to disk. This lets you review diffs before committing to a refactoring.

Example (as a natural language prompt to Claude):

"Preview what would happen if I renamed OrderProcessor to OrderHandler in C:/path/to/MySolution.sln"

Claude will call rename_symbol with preview: true and show you the affected files and diffs.

Troubleshooting

.NET 9 SDK not found

If you see errors about the SDK not being found:

1. Verify the SDK is installed: dotnet --list-sdks
2. Make sure .NET 9.0 or later appears in the list
3. If not, install it from https://dotnet.microsoft.com/download/dotnet/9.0

MSBuild or solution loading issues

If MSBuild cannot be located or your solution fails to load:

1. Make sure you can build the solution from the command line first: dotnet build /path/to/MySolution.sln
2. On Windows, ensure Visual Studio Build Tools or a Visual Studio installation is available
3. Check that solutionPath is an absolute path to a valid .sln, .slnx, or .csproj file

Using the diagnose tool

The diagnose tool is the first thing to try when something is not working. It reports:

• Whether Roslyn is loaded and its version
• Whether MSBuild was found and its version
• Whether the .NET SDK is available and its version
• Whether a given solution can be loaded, including project and document counts

Run it through Claude:

"Run the roslyn diagnose tool with verbose output for C:/path/to/MySolution.sln"

Or without a solution path to check just the environment:

"Run the roslyn diagnose tool"

NuGet Libraries

In addition to the global tool, the project publishes libraries for building custom integrations:

# Core library -- refactoring operations and workspace management
dotnet add package RoslynMcp.Core

# Contracts library -- shared models and interfaces
dotnet add package RoslynMcp.Contracts

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

Build from Source

git clone https://github.com/JoshuaRamirez/RoslynMcpServer.git
cd RoslynMcpServer
dotnet build -c Release

Run Tests

# All tests
dotnet test

# Specific test projects
dotnet test tests/RoslynMcp.Core.Tests
dotnet test tests/RoslynMcp.Server.Tests
dotnet test tests/RoslynMcp.Cli.Tests

License

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

Acknowledgments

• Built with Roslyn -- the .NET Compiler Platform
• Implements the Model Context Protocol

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions