mcp powershell

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:

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

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
2. You may need to adjust your PowerShell execution policy to allow script execution

3. Use Set-ExecutionPolicy RemoteSigned -Scope CurrentUser to allow local scripts

4. Path not found errors

5. Ensure file paths are absolute or properly relative to the working directory

6. Use appropriate path separators for your OS

7. Command not found errors

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

License

MIT