# How to Integrate Desktop Commander with Cursor and Windsurf: A Complete Plugin Guide

> Integrate Desktop Commander with Cursor and Windsurf using our complete plugin guide. Learn how to map client APIs to shared skill modules with YAML and TypeScript.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-07-25

---

**Desktop Commander integrates with AI clients like Cursor and Windsurf through a modular plugin system that maps client APIs to shared skill modules via a YAML manifest and TypeScript entry point.**

Desktop Commander MCP is a plugin-first desktop automation framework that exposes system capabilities to AI-assisted coding environments. By leveraging the modular architecture found in the `wonderwhy-er/DesktopCommanderMCP` repository, you can extend support to any client that exposes a JavaScript API, including Cursor and Windsurf.

## Understanding the Plugin Architecture

The core runtime discovers and loads plugins from the `plugins/` directory at startup. Each plugin supplies a [`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml) (or [`plugin.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.json)) manifest that declares the target client, required permissions, and entry points. According to the source code in [`src/remote-device/README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/README.md), the core loader reads these manifests, resolves dependencies, and registers the plugin with the command dispatcher.

The architecture separates client-specific wrappers from reusable functionality:

- **Client plugins** (`plugins/cursor/`, `plugins/claude/`) contain thin wrappers that translate client APIs (e.g., `window.ai` or `window.windsurf`) into Desktop Commander commands
- **Skill modules** ([`skills/terminal/SKILL.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/skills/terminal/SKILL.md)) implement actual functionality like shell execution or file browsing
- **Configuration files** ([`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json)) control which plugins are enabled without requiring code changes

## Creating a Client Plugin for Windsurf

To integrate a new client such as Windsurf, create a directory at `plugins/windsurf/` following the structure established in [`plugins/cursor/README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugins/cursor/README.md) and [`plugins/claude/README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugins/claude/README.md).

### Step 1: Define the Plugin Manifest

Create [`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml) to declare the plugin metadata and permissions:

```yaml
name: windsurf
displayName: Windsurf Integration
description: Enables Desktop Commander features inside the Windsurf AI client.
version: 0.1.0
entry: src/index.ts
permissions:
  - filesystem
  - network

```

This manifest tells the core loader in [`src/remote-device/README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/README.md) where to find the entry point and what capabilities to grant the plugin.

### Step 2: Implement the Entry Point

Create [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts) to register the plugin with the Desktop Commander SDK and import required skills:

```typescript
import { registerPlugin } from '@desktop-commander/sdk';
import { terminalSkill } from '../../skills/terminal/skill';
import { fileBrowserSkill } from '../../skills/file-browser/skill';

// Register the plugin with the Desktop Commander core
registerPlugin('windsurf', (api) => {
  // Expose a "run command" method that Windsurf can call
  api.expose('runShell', (command: string) => {
    return terminalSkill.execute(command);
  });

  // Expose a "open file" method
  api.expose('openFile', (path: string) => {
    return fileBrowserSkill.open(path);
  });
});

```

The `registerPlugin` function binds your client to the Desktop Commander runtime, while `api.expose` makes methods available on the `window.desktopCommander` object.

### Step 3: Invoke Commands from the Client

Once loaded, the Windsurf client can access Desktop Commander capabilities through the global API:

```javascript
// Inside a Windsurf extension script
window.desktopCommander.runShell('ls -la')
  .then((output) => console.log(output));

window.desktopCommander.openFile('/home/user/project/README.md');

```

## Enabling and Configuring the Integration

Add your new plugin to [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) (or [`plugin.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.json)) to enable loading without modifying core code:

```json
{
  "enabledPlugins": ["cursor", "claude", "windsurf"]
}

```

The root [`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml) and [`plugin.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.json) files serve as global registries that mirror this configuration for JSON-friendly consumers. The runtime automatically picks up new plugins on the next launch or during hot-reload cycles.

## Leveraging Shared Skill Modules

Desktop Commander's modular design centralizes heavy lifting in reusable skill packages. The [`skills/terminal/SKILL.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/skills/terminal/SKILL.md) file, for example, implements terminal execution logic used by all client plugins. When building a new integration, you import these pre-built skills rather than reimplementing functionality:

- **Terminal operations**: `skills/terminal/skill`
- **File browsing**: `skills/file-browser/skill`
- **Knowledge base queries**: Available through the skills directory structure

This approach ensures that bug fixes and feature enhancements to core capabilities propagate to all connected clients automatically.

## Summary

- Desktop Commander uses a plugin architecture defined by manifests in [`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml) files and entry points in [`src/index.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/index.ts)
- New clients require only a lightweight wrapper in the `plugins/` directory that maps client APIs to the `window.desktopCommander` object
- Reusable capabilities are centralized in the `skills/` directory (e.g., [`skills/terminal/SKILL.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/skills/terminal/SKILL.md)) and shared across all client integrations
- Enable new integrations by adding the plugin name to [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) without touching core loader code in [`src/remote-device/README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/README.md)

## Frequently Asked Questions

### What file format does Desktop Commander use for plugin manifests?

Desktop Commander supports both [`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml) and [`plugin.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.json) manifest files located in each plugin's root directory. These files declare the plugin name, entry point, version, and required permissions such as filesystem or network access.

### Do I need to modify the core Desktop Commander code to add Windsurf support?

No. The modular architecture allows you to add new client support by creating a new folder under `plugins/` (e.g., `plugins/windsurf/`) following the patterns in [`plugins/cursor/README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugins/cursor/README.md) and [`plugins/claude/README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugins/claude/README.md). The core loader automatically discovers and registers new plugins at startup.

### Where are the terminal and file system capabilities defined?

Reusable capabilities are implemented as skill modules in the `skills/` directory. For example, [`skills/terminal/SKILL.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/skills/terminal/SKILL.md) contains the terminal execution logic imported by client plugins via `import { terminalSkill } from '../../skills/terminal/skill'`.

### How does the plugin system handle security permissions?

Permissions are declared explicitly in each plugin's [`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml) manifest under the `permissions` key (e.g., `filesystem`, `network`). The core loader in [`src/remote-device/README.md`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/README.md) reads these declarations and enforces capability restrictions when registering the plugin with the command dispatcher.