← Back to Home
Manual Setup

Manual Setup Guide

After pip install heropen, your agent still needs to connect via MCP.
Pick your tool below, follow the steps, and you're done in 3 minutes.

00 One-Click Auto Setup (Recommended)

Run this first after install — works for most cases.

heropen auto-setup Auto

Automatically detects agents installed on your machine (Cline / Cursor / Windsurf / Claude Code etc.), scans their MCP config files, and injects HeroPen automatically.

pip install heropen
heropen auto-setup
✅ After running, restart your Agent — it will have memory.

If auto-setup doesn't find your tool, or you want to configure manually, continue below.

01 What MCP Configuration Looks Like

All agents use the same JSON format for MCP config — only the file path and minor syntax differ.

Core Config Standard Format

This JSON tells your agent: "start a command named heropen with argument mcp, communicating over stdin/stdout." 

{
  "mcpServers": {
    "heropen": {
      "command": "heropen",
      "args": ["mcp"],
      "disabled": false
    }
  }
}
💡 How it works: The agent starts a heropen-mcp subprocess that exchanges tool calls via stdin/stdout. Every agent uses the same format — only the file location changes.

02 WorkBuddy

WorkBuddy on Windows has the simplest configuration.

Config File Manual

  1. Navigate to C:\Users\YourUser\.workbuddy\
  2. Create or edit mcp.json
  3. Paste the following:
{
  "mcpServers": {
    "heropen": {
      "command": "heropen",
      "args": ["mcp"],
      "disabled": false
    }
  }
}
  1. Save the file
  2. Completely close WorkBuddy (exit from the taskbar, not just the window), then reopen
⚠️ Important: If you've configured multiple MCP servers (e.g. Feishu connector-proxy), add heropen alongside them.

Multi-MCP Example Example

If you're using both Feishu MCP and HeroPen:

{
  "mcpServers": {
    "connector-proxy": {
      "type": "http",
      "url": "http://127.0.0.1:59489/mcp",
      "description": "feishu MCP"
    },
    "heropen": {
      "command": "heropen",
      "args": ["mcp"],
      "disabled": false
    }
  }
}

03 Cline (VS Code Extension)

Cline is the most popular MCP Agent extension for VS Code.

Config File Location Manual

Windows: %APPDATA%\Claude\cline_mcp_settings.json
macOS: ~/Library/Application Support/Claude/cline_mcp_settings.json
Linux: ~/.config/Claude/cline_mcp_settings.json

Open the corresponding file and add to mcpServers:

{
  "mcpServers": {
    "heropen": {
      "command": "heropen",
      "args": ["mcp"],
      "disabled": false
    }
  }
}
✅ Save and restart VS Code — Cline will load automatically. Try asking Cline "how many memories does heropen have?"

04 Cursor

Cursor's MCP config works at both project level and global level.

Global Config Manual

  1. Open Cursor → Settings → Features → MCP Servers
  2. Click "Add MCP Server"
  3. Name enter heropen
  4. Type select command
  5. Command enter heropen mcp
  6. Click Save

Or edit the global config file directly:

# macOS/Linux: ~/.cursor/mcp.json
# Windows: C:\Users\YourUser\.cursor\mcp.json

{
  "mcpServers": {
    "heropen": {
      "command": "heropen",
      "args": ["mcp"],
      "disabled": false
    }
  }
}

05 Claude Code CLI

Project-level configuration for Claude Code.

Project Config Manual

Create or edit in your project root:

# .claude/settings.json (relative to project root)
# Or ~/.claude/settings.json (global)

{
  "mcpServers": {
    "heropen": {
      "command": "heropen",
      "args": ["mcp"],
      "disabled": false
    }
  }
}
✅ Claude Code will auto-load on next launch.

06 Cherry Studio

Cherry Studio has a UI-based configuration.

UI Configuration Manual

  1. Open Cherry Studio → Settings → MCP Client
  2. Click "Add MCP Server"
  3. Name: heropen
  4. Command: heropen
  5. Args: mcp
  6. Save

Or edit the config file directly:

# Windows: %APPDATA%\CherryStudio\mcp.json
# macOS: ~/Library/Application Support/CherryStudio/mcp.json

{
  "mcpServers": {
    "heropen": {
      "command": "heropen",
      "args": ["mcp"],
      "disabled": false
    }
  }
}

07 Continue.dev

Continue's global config file.

Global Config Manual

# macOS/Linux: ~/.continue/config.json
# Windows: C:\Users\YourUser\.continue\config.json

{
  "experimental": {
    "mcpServers": {
      "heropen": {
        "command": "heropen",
        "args": ["mcp"],
        "disabled": false
      }
    }
  }
}
⚠️ Continue's MCP config lives under the experimental field. If you already have other MCP servers, add directly inside the same object.

08 Verify Configuration

No matter which method you used, run this in your terminal to confirm.

Terminal Verification Confirm

heropen status

If it shows memory count, agent info, and running status, HeroPen is working.

🎯 Perfect verification: Ask your agent
"How many memories does heropen have? Check it"
If it answers, you're all set.

Troubleshooting FAQ

  1. "MCP error -32000: Connection closed" → First check that you have the latest version (pip install --upgrade heropen), then verify your JSON format is correct
  2. "Command heropen not found" → Python is not in your PATH, use python -m heropen mcp instead
  3. Config changes not taking effect → Completely close and restart your agent (not just the window)
  4. JSON errors on Windows → Save the file as UTF-8 encoding, not UTF-8 with BOM