What is Mcp Powershell

mcp-powershell is a Model Context Protocol server designed for interacting with PowerShell. It provides tools for executing PowerShell commands, retrieving system information, managing modules, and more.

Use cases

Use cases for mcp-powershell include automating system tasks, gathering system diagnostics, managing PowerShell modules, and providing help for PowerShell commands in development environments.

How to use

To use mcp-powershell, first install the required dependencies using ‘npm install’, then build the project with ‘npm run build’. Configure the server in your desired application (Claude Desktop, VS Code, or Cursor IDE) by editing the respective configuration files to include the server command and arguments.

Key features

Key features of mcp-powershell include executing PowerShell commands, retrieving detailed system information, listing installed PowerShell modules, and obtaining help for specific PowerShell commands.

Where to use

mcp-powershell can be used in various fields such as software development, system administration, and IT operations where PowerShell scripting and automation are required.

PowerShell MCP Server

A Model Context Protocol server for interacting with PowerShell. This server provides tools for executing PowerShell commands, retrieving system information, managing modules, and more.

Requirements

• Node.js 18+
• PowerShell 5.1 or PowerShell Core 7+

Installation

1. Install dependencies:

   npm install
   

2. Build the project:

   npm run build
   

Configuration

For Claude Desktop

Edit config: $HOME/Library/Application\ Support/Claude/claude_desktop_config.json

Add to mcpServers:

{
  "mcpServers": {
    "mcp-powershell": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-powershell/dist/index.js"
      ]
    }
  }
}

For VS Code

Edit config: $HOME/Library/Application\ Support/Code/User/settings.json

Add to settings:

For Cursor IDE

Edit config: $HOME/.cursor/mcp.json

Add to mcpServers:

{
  "mcpServers": {
    "mcp-powershell": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-powershell/dist/index.js"
      ]
    }
  }
}

Available Tools

This PowerShell MCP server provides the following tools:

execute_ps

Execute a PowerShell command and get the result.

Parameters:
- command (string): PowerShell command to execute

Example usage:

execute_ps(command: "Get-Process | Select-Object -First 5")

get_system_info

Retrieve detailed system information, including OS details, processor, memory, and PowerShell version.

Parameters: None

Example usage:

get_system_info()

list_modules

List all installed PowerShell modules with details like name, version, and type.

Parameters: None

Example usage:

list_modules()

get_command_help

Get detailed help for a specific PowerShell command, including syntax, parameters, and examples.

Parameters:
- command (string): PowerShell command to get help for

Example usage:

get_command_help(command: "Get-Process")

find_commands

Search for PowerShell commands by name or pattern.

Parameters:
- search (string): Search term for PowerShell commands

Example usage:

find_commands(search: "Process")

run_script

Run a PowerShell script file with optional parameters.

Parameters:
- scriptPath (string): Path to the PowerShell script file
- parameters (string, optional): Optional parameters to pass to the script

Example usage:

run_script(scriptPath: "/path/to/script.ps1", parameters: "-Name 'Test' -Value 123")

Development

To run in development mode:

npm run dev

Extending the Server

To add your own PowerShell tools:

1. Edit src/index.ts
2. Add new tools in the registerTools() method
3. Follow the existing pattern for consistent error handling
4. Build with npm run build

Adding a Tool Example

// In the registerTools() method:
this.server.tool(
  "my_ps_tool",
  {
    param1: z.string().describe("Description of parameter 1"),
    param2: z.number().optional().describe("Optional numeric parameter"),
  },
  async ({ param1, param2 }) => {
    try {
      // Your PowerShell command
      const command = `Your-PowerShell-Command -Param1 "${param1}" ${param2 ? `-Param2 ${param2}` : ''}`;

      const { stdout, stderr } = await execAsync(`powershell -Command "${command.replace(/"/g, '\\"')}"`);

      if (stderr) {
        return {
          isError: true,
          content: [
            {
              type: "text" as const,
              text: `Error in my_ps_tool: ${stderr}`,
            },
          ],
        };
      }

      return {
        content: [
          {
            type: "text" as const,
            text: stdout,
          },
        ],
      };
    } catch (error) {
      return {
        isError: true,
        content: [
          {
            type: "text" as const,
            text: `Error in my_ps_tool: ${(error as Error).message}`,
          },
        ],
      };
    }
  }
);

Security Considerations

• This server executes PowerShell commands directly on your system
• Commands are executed with the same privileges as the process running the MCP server
• Use caution when exposing destructive operations
• Consider implementing additional validation for sensitive commands

Troubleshooting

Common Issues

1. PowerShell execution policy restrictions

   • You may need to adjust your PowerShell execution policy to allow script execution
   • Use Set-ExecutionPolicy RemoteSigned -Scope CurrentUser to allow local scripts

2. Path not found errors

   • Ensure file paths are absolute or properly relative to the working directory
   • Use appropriate path separators for your OS

3. Command not found errors

   • Some commands may require specific modules to be installed
   • Use Install-Module ModuleName to install required modules

License

MIT