Pieces MCP + Claude Desktop Integration

The Pieces MCP integration with Claude Desktop lets you use Pieces Long-Term Memories captured by PiecesOS without any third-party applications.

Get Started

Integrating the Pieces MCP with Claude Desktop is a powerful way to bring your workflow context directly into your AI assistant.

With this integration, you'll have an in-Desktop Claude agent that knows more about your projects than just the files you copy and paste.

You can ask questions about prior work, like “What decision did I make in last week’s sprint review?” and instantly reuse that context without searching through notes or commits.

Learn how to integrate the Pieces MCP into Claude Desktop by following the steps below.

It is imperative that you download and/or update Claude Desktop to the latest, most up-to-date version to ensure compatibility with Pieces MCP.

Prerequisites

There are two main things you need to do to connect Pieces with Claude Desktop as an MCP: have an active PiecesOS and turn on the Long-Term Memory engine.

1

Install & Run PiecesOS

Ensure PiecesOS is installed and running. This lets the MCP server connect with your workflow data and share context with Claude.

If you don't have PiecesOS, you can download it with the Pieces Desktop App or get it separately here.

2

Enable Long-Term Memory

To let the MCP server use your workflow context, you need to turn on the Long-Term Memory Engine (LTM-2.5) through the Pieces Desktop App or the PiecesOS Quick Menu in your toolbar.

Installing PiecesOS & Configuring Permissions

Follow the instructions below for a detailed guide on setting up and configuring PiecesOS to correctly pass captured workflow context to the Pieces MCP server.

Installing PiecesOS for macOS

Download the standalone PiecesOS file for your macOS system’s ARM or Intel-based architecture to start the installation process.

Your device must be updated to macOS 13.0 (Ventura) or higher.

  1. Download the correct PiecesOS file for your system’s architecture.

  2. From your Downloads folder, double-click the installed PiecesOS file to open it.

  3. Drag PiecesOS into the application folder if prompted, then open PiecesOS.

Configuring Permissions

There are two permissions prompts that will pop up on your screen when installing PiecesOS.

PiecesOS is an app downloaded from the internet. Are you sure you want to open it?

Click Open to continue with the installation.

Then, you’ll see a second permissions pop-up message:

PiecesOS is requesting to bypass the system private window picker and directly access your screen and audio. This will allow PiecesOS to record your screen and system audio, including personal or sensitive information that may be visible or audible.

Click Allow.

These permissions are required for PiecesOS to power the Long-Term Memory Engine (LTM-2) and, in turn, capture context from your workflow to provide information to the Pieces MCP server.

PiecesOS will automatically open in your toolbar and pop up a Notification preferences modal in the upper right corner of your screen.

Enabling the LTM-2 Engine

For the Pieces MCP to function, Long-Term Memory must be enabled.

To do this, open up the PiecesOS Quick Menu and click Enable Long-Term Memory Engine.

Setting Up Claude Desktop

There are two methods to set up the Pieces MCP for Claude Desktop—either configuring the server connection manually with a direct command, or using the Pieces CLI to configure it automatically.

Method 1: Manual Configuration (Direct MCP Command)

This method involves editing Claude Desktop’s MCP configuration file to point directly to a CLI command that starts the Pieces MCP server.

With this method, the Claude MCP config points to the Pieces CLI executable and runs pieces mcp start whenever Claude starts. This is different from using the CLI to configure Claude directly (Method 2).

1

Install the Pieces CLI

Make sure the Pieces CLI is installed.

In your terminal, run the following commands:

py -m pip install --upgrade pip
py -m pip install pieces-cli

Next, confirm that the installation was successful:

pieces --version
2

Locate the Pieces CLI Executable

The executable path depends on your OS and Python installation method.

For example:

  1. Windows → C:\Users\<YourUser>\AppData\Local\Programs\Python\Python3XX\Scripts\pieces

  2. macOS → usr/local/bin/pieces

  3. Linux → home/<YourUserNameHere>/.local/bin/pieces

3

Locate or Create the Claude Desktop Config File

Claude Desktop stores its MCP configuration in a user-specific location for each OS.

Depending on your platform, this might be:

  1. Windows → C:\Users\<YourUser>\AppData\Roaming\Claude\claude_desktop_config.json

  2. macOS → ~/Library/Application Support/Claude/claude_desktop_config.json

  3. Linux → ~/.config/Claude/claude_desktop_config.json

If the file exists → open it in a text editor.
If it doesn’t exist → create it manually in that directory.

4

Add MCP Server Configuration

Paste the following JSON, adjusting the path to your pieces.exe if different:

jsonCopyEdit{
  "mcpServers": {
    "Pieces": {
      "command": "C:\\Users\\<YourUser>\\AppData\\Local\\Programs\\Python\\Python313\\Scripts\\pieces.exe",
      "args": [
        "--ignore-onboarding",
        "mcp",
        "start"
      ]
    }
  }
}
5

Save & Restart Claude Desktop

Fully quit and reopen Claude Desktop.

6

Enable Pieces MCP

Start prompting Claude—if properly set up, you will be prompted by Claude to enable and allow (on a case-by-case basis, or via always allow) Claude to pass prompts through the ask_pieces_ltm tool.

This utility communicates with PiecesOS and your local repository of saved workflow context.

Method 2: Using the Pieces CLI to Configure Automatically

This method uses the Pieces CLI to automatically set up and configure Pieces MCP for Claude Desktop.

1

Install the Pieces CLI

Run the following commands to install the Pieces CLI if you haven’t already done so.

-m pip install --upgrade pip
py -m pip install pieces-cli
2

Run the Automatic Setup Command

Run:

pieces mcp setup --claude

This will:

  • Detect your Claude Desktop MCP config location.

  • Insert the correct mcpServers entry for Pieces.

  • Point Claude directly to the MCP server without requiring manual JSON edits.

3

Restart Claude Desktop

Once the command completes, restart Claude Desktop and confirm that the Pieces MCP server is connected.

Using Pieces MCP Server in Claude Desktop

Once integrated, you can utilize Pieces LTM directly in Claude Desktop.

  1. Open a Claude Chat
    Launch a new conversation in Claude Desktop.

  2. Prompt with Context
    Ask Claude questions about prior work or files (e.g., “What was I doing for work yesterday?”).

  1. Verify MCP Tools Are Active
    If configured correctly, Claude will automatically use the ask_pieces_ltm tool to pull relevant context.

Troubleshooting

If you’re experiencing issues integrating Pieces MCP with Claude Desktop:

  1. Verify PiecesOS Status
    Ensure PiecesOS is actively running on your system.

  2. Confirm LTM Engine Activation
    Long-Term Memory (LTM-2.5) must be enabled in PiecesOS.

  3. Single MCP Instance
    Avoid running multiple Pieces MCP instances in different apps simultaneously.

  4. Check MCP Server Status in Claude
    Use the Developer Console (Ctrl+Shift+I) to confirm connection messages.

  5. Review Configuration
    If using Method 1, ensure your JSON paths are correct.
    If using Method 2, rerun:

    pieces mcp setup --claude

You’re now ready to enhance your Claude Desktop experience with the Pieces MCP, enabling powerful, context-aware conversations and seamless access to your workflow history.

Updated on
MCP -> Goose
Visual Studio Code Extension