# Manus MCP

The Universal MCP Server for Manus AI enables you to create AI tasks, manage webhooks, and integrate Manus workflows into any MCP-compatible client. Designed for prompt-first usage with full support for attachments, connectors, and real-time notifications.

## Installation

### Prerequisites
- Node.js 18+
- Set `MANUS_MCP_API_KEY` in your environment

### Get an API key
- Request your API key from the [Manus Dashboard](https://manus.ai)
- API documentation: https://open.manus.ai/docs
- Getting started guide: https://open.manus.ai/docs/quickstart

### Build locally
```bash
cd /path/to/manus-mcp
npm i
npm run build
```

## Setup: Claude Code (CLI)

Use this one-liner (replace with your real API key):

```bash
claude mcp add manus-mcp -s user -e MANUS_MCP_API_KEY="your-api-key-here" -- npx manus-mcp
```

**Note**: Use `manus-mcp` (not `"Manus MCP"`) as the name. Claude CLI requires names without spaces.

To remove:

```bash
claude mcp remove manus-mcp
```

## Setup: Cursor

Create `.cursor/mcp.json` in your client (do not commit it here):

```json
{
  "mcpServers": {
    "manus-mcp": {
      "command": "npx",
      "args": ["manus-mcp"],
      "env": { "MANUS_MCP_API_KEY": "your-api-key-here" },
      "autoStart": true
    }
  }
}
```

**Note**: This repository does not include `.cursor/mcp.json`. Configure Cursor via the UI or manually create the file in your client workspace.

## Other Clients and Agents

<details>
<summary>VS Code</summary>

Install via URI or CLI:

```bash
code --add-mcp '{"name":"manus-mcp","command":"npx","args":["manus-mcp"],"env":{"MANUS_MCP_API_KEY":"your-api-key-here"}}'
```

Or add to your VS Code settings JSON:

```json
{
  "mcp.servers": {
    "manus-mcp": {
      "command": "npx",
      "args": ["manus-mcp"],
      "env": { "MANUS_MCP_API_KEY": "your-api-key-here" }
    }
  }
}
```

</details>

<details>
<summary>VS Code Insiders</summary>

Same as VS Code, but use `code-insiders` command:

```bash
code-insiders --add-mcp '{"name":"manus-mcp","command":"npx","args":["manus-mcp"],"env":{"MANUS_MCP_API_KEY":"your-api-key-here"}}'
```

</details>

<details>
<summary>Claude Desktop</summary>

Add to your Claude Desktop configuration file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "manus-mcp": {
      "command": "npx",
      "args": ["manus-mcp"],
      "env": { "MANUS_MCP_API_KEY": "your-api-key-here" }
    }
  }
}
```

</details>

<details>
<summary>LM Studio</summary>

In LM Studio's MCP settings:

- **Command**: `npx`
- **Args**: `["manus-mcp"]`
- **Env**: `MANUS_MCP_API_KEY=your-api-key-here`

</details>

<details>
<summary>Goose</summary>

Add to your Goose configuration:

- **Type**: STDIO
- **Command**: `npx`
- **Args**: `manus-mcp`
- **Enabled**: true
- **Env**: `MANUS_MCP_API_KEY=your-api-key-here`

</details>

<details>
<summary>opencode</summary>

Example `~/.config/opencode/opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "manus-mcp": {
      "type": "local",
      "command": ["npx", "manus-mcp"],
      "enabled": true,
      "env": { "MANUS_MCP_API_KEY": "your-api-key-here" }
    }
  }
}
```

</details>

<details>
<summary>Qodo Gen</summary>

Add a new MCP in Qodo Gen and paste the standard JSON config:

```json
{
  "command": "npx",
  "args": ["manus-mcp"],
  "env": { "MANUS_MCP_API_KEY": "your-api-key-here" }
}
```

</details>

<details>
<summary>Windsurf</summary>

Follow the Windsurf MCP integration guide and reuse the standard config:

```json
{
  "manus-mcp": {
    "command": "npx",
    "args": ["manus-mcp"],
    "env": { "MANUS_MCP_API_KEY": "your-api-key-here" }
  }
}
```

</details>

## Setup: Codex (TOML)

Add the following to your Codex TOML configuration:

```toml
[mcp_servers.manus-mcp]
command = "npx"
args = ["manus-mcp"]

[mcp_servers.manus-mcp.env]
MANUS_MCP_API_KEY = "your-api-key-here"
# MCP_NAME = "manus-mcp"  # Optional: override server name
```

## Configuration (Env)

- **MANUS_MCP_API_KEY**: Your Manus API key (required)
- **MANUS_MCP_API_BASE_URL**: Override the API base URL (default: `https://api.manus.ai/v1`)
- **MCP_NAME**: Server name override (default: `manus-mcp`)

## Available Tools

### `create_task`

Create a new AI task in Manus with custom parameters and optional attachments.

**Inputs**:
```json
{
  "prompt": "string (required) - The task prompt or instruction for the AI",
  "mode": "string (required) - 'speed' or 'quality'",
  "attachments": "array (optional) - List of attachment objects { filename, url, mime_type, size_bytes }",
  "connectors": "array (optional) - List of connector IDs (e.g., ['gmail', 'notion'])",
  "hide_in_task_list": "boolean (optional) - Hide from webapp task list (default: false)",
  "create_shareable_link": "boolean (optional) - Generate a public shareable link (default: false)"
}
```

**Outputs**:
```json
{
  "task_id": "string - Unique task identifier",
  "task_title": "string - Generated task title",
  "task_url": "string - Direct link to the task",
  "shareURL": "string (optional) - Public shareable link if requested"
}
```

### `create_webhook`

Register a new webhook to receive real-time notifications from Manus.

**Inputs**:
```json
{
  "url": "string (required) - Webhook endpoint URL",
  "events": "array (optional) - List of event types to subscribe to"
}
```

**Outputs**:
Webhook registration details including webhook ID and configuration.

### `delete_webhook`

Remove a previously registered webhook by its ID.

**Inputs**:
```json
{
  "webhook_id": "string (required) - The ID of the webhook to delete"
}
```

**Outputs**:
Success confirmation or error details.

## Example invocation (MCP tool call)

Create a task in speed mode:

```json
{
  "tool": "create_task",
  "arguments": {
    "prompt": "Analyze the quarterly sales data and generate a summary report with key insights",
    "mode": "speed",
    "create_shareable_link": true
  }
}
```

Create a task with attachments:

```json
{
  "tool": "create_task",
  "arguments": {
    "prompt": "Extract key action items from this meeting transcript",
    "mode": "quality",
    "attachments": [
      {
        "filename": "meeting-notes.pdf",
        "url": "https://example.com/files/meeting-notes.pdf",
        "mime_type": "application/pdf",
        "size_bytes": 245632
      }
    ],
    "connectors": ["gmail", "notion"]
  }
}
```

## Troubleshooting

### 401 Authentication Error
- Verify that `MANUS_MCP_API_KEY` is correctly set in your environment
- Check that your API key is valid and has not expired
- Test your API key with a direct curl request:
  ```bash
  curl -H "API_KEY: your-key" https://api.manus.ai/v1/tasks
  ```

### Node.js Version Error
- Ensure you're using Node.js 18 or later: `node -v`
- Update Node.js if necessary: https://nodejs.org/

### Build Issues
- Clear the build directory: `rm -rf build`
- Reinstall dependencies: `rm -rf node_modules && npm i`
- Rebuild: `npm run build`

### Testing Local Builds
- After building, test the server: `npx .` or `node build/index.js`
- Check that the executable is properly created: `ls -la build/index.js`

### Inspecting Publish Artifacts
- See what would be published: `npm pack --dry-run`
- Check the package contents: `npm pack && tar -xzf manus-mcp-*.tgz && cat package/package.json`

## References

- **Manus API Documentation**: https://open.manus.ai/docs
- **MCP SDK**: https://modelcontextprotocol.io/docs/sdks
- **MCP Architecture**: https://modelcontextprotocol.io/docs/learn/architecture
- **MCP Server Concepts**: https://modelcontextprotocol.io/docs/learn/server-concepts
- **MCP Server Specification**: https://modelcontextprotocol.io/specification/2025-06-18/server/index
- **Manus Quickstart**: https://open.manus.ai/docs/quickstart
- **Manus Webhooks**: https://open.manus.ai/docs/webhooks/overview
- **Manus Connectors**: https://open.manus.ai/docs/connectors/overview

## Name Consistency & Troubleshooting

Always use **CANONICAL_ID** (`manus-mcp`) for identifiers and keys. Use **CANONICAL_DISPLAY** (`Manus MCP`) only for UI labels. Do not mix legacy keys after registration.

### Consistency Matrix

| Context                       | Value         |
|-------------------------------|---------------|
| npm package name              | `manus-mcp`   |
| Binary name                   | `manus-mcp`   |
| MCP server name (SDK metadata)| `manus-mcp`   |
| Env default MCP_NAME          | `manus-mcp`   |
| Client registry key           | `manus-mcp`   |
| UI label                      | `Manus MCP`   |

### Conflict Cleanup

- Remove any stale keys (e.g., old display names like "Manus") and re-add with `manus-mcp` only
- Ensure global `.mcp.json` or client registries only use `manus-mcp` for keys
- **Cursor**: Configure in the UI; this project intentionally omits `.cursor/mcp.json`

### Example

✅ **Correct**:
```json
{
  "mcpServers": {
    "manus-mcp": {
      "command": "npx",
      "args": ["manus-mcp"]
    }
  }
}
```

❌ **Incorrect**:
```json
{
  "mcpServers": {
    "Manus": {  // Wrong: will conflict with "manus-mcp"
      "command": "npx",
      "args": ["manus-mcp"]
    }
  }
}
```

---

## License

MIT