Merlin Project includes a built-in MCP server, a lightweight local helper that lets AI clients such as Claude Code,Cursor, Codex, or Antigravity interact directly with Merlin Project. Through the MCP server, these tools can read project data and make changes in your Merlin Project documents using a defined set of MCP commands (also called tools).

When an AI client connects to the Merlin Project MCP server, it automatically learns which tools are available and how to use them. These details are supplied by the server and injected into the model’s context, allowing the model to reason about Merlin-specific actions and pick the most suitable tool for the job.

What Is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI clients connect to external applications in a structured, secure way. Instead of pasting screenshots or copying data back and forth, your AI assistant can read information from Merlin Project directly — inspecting the active project, looking up activities, milestones, resources, or assignments, and using that context to answer your questions or generate reports on your behalf.

Typical Use Cases

You generally don’t need to specify which tool the AI should call — the client decides that on its own based on your prompt. Here are some examples of the kinds of requests you can make:

  • Summarize the current status of the active project, highlighting completed milestones and upcoming deadlines.

  • Generate a status report or stakeholder update from the current project data.

  • Identify activities that are at risk of slipping based on the current schedule.

  • List all unassigned activities, or all activities assigned to a specific resource.

  • Explain the critical path and which activities drive the project end date.

  • Check the project for inconsistencies, such as missing dependencies or unrealistic durations.

  • Translate every activity title in the current project into another language (as output).

  • Export all activities from a selected group as a checklist or Markdown table.

The prompts above are basic examples. A good prompt typically includes more detail, breaks the task into well-defined steps, provides rules for your AI client to follow, and suggests how to validate the result.

Security

The MCP server runs locally on your Mac and cannot be accessed remotely. Each call is handled locally by Merlin Project itself, and the results are returned to the AI client for further processing. You have full control over when and how external AI clients connect to it.

Enabling Access to a Project

By default, the contents of a Merlin Project document are not available to any AI assistant — even when the MCP server is installed and running. You need to enable access explicitly for each project you want an AI assistant to read.

To enable access for the active document, click the AI Tools item in the document’s toolbar. A popover opens with a checkbox that allows access from MCP servers. Once you tick the box, the toolbar icon appears filled to indicate that access is enabled. While an AI assistant is actively connected to the project through an MCP server, the icon is additionally shown with a blue accent color .

You can revoke access at any time by opening the popover again and clearing the checkbox.

How to Connect Your AI Client

The following sections explain how to connect the Merlin Project MCP server to a range of AI clients.

Claude Code

Claude Code must be installed and running in your terminal before you can connect it to the Merlin Project MCP server. If you haven’t set it up yet, install Claude Code before continuing.

  1. Install the Merlin MCP Server from Main Menu  Merlin Project  Install MCP Server.

  2. Connect Claude Code to the Merlin Project MCP server by running:

    claude mcp add --transport stdio merlin-project -- /usr/local/bin/merlinproject-mcp

  3. Verify that Claude Code is connected to the server:

    claude mcp get merlin-project

Claude Desktop

  1. In the Claude Desktop app, go to Claude  Settings  Developer and click Edit Config.

  2. The file claude_desktop_config.json is highlighted in the Finder

  3. Open the file with a text editor like Text Edit.

  4. Add the following entry to the file and save:

    {
  "mcpServers": {
    "merlin-project": {
      "command": "/usr/local/bin/merlinproject-mcp"
    }
  }
}
    If the file already contains content — whether other MCP servers, preferences, or any other settings — do not overwrite it. Leave all existing top-level keys in place, make sure a "mcpServers" object exists at the top level (create it if necessary), and add the "merlin-project" entry inside it, separated from any sibling entries by a comma. This keeps the file valid JSON. If the file is empty or doesn’t exist yet, paste the snippet above as-is.

  5. Quit and restart the Claude Desktop app.

Visual Studio Code

  1. Install the Merlin MCP Server from Main Menu  Merlin Project  Install MCP Server.

  2. Press ⌘+⇧+P to open the Command Palette and type MCP Add.

  3. Select the MCP: Add Server option.

  4. When prompted for the server type, select Command (stdio).

  5. When prompted for the command to run, paste the following path:

    /usr/local/bin/merlin-project

  6. Give the server a name, for example merlin-project.

  7. Press ⌘+⇧+I to open a new Copilot chat in Agent mode.

Cursor

  1. Install the Merlin MCP Server from Main Menu  Merlin Project  Install MCP Server.

  2. Open Cursor  Preferences  Cursor Settings.

  3. Navigate to the Tools & MCPs tab.

  4. Click New MCP Server.

  5. Add the following entry to the auto-generated mcp.json file:

    {
  "mcpServers": {
    "merlin-project": {
      "command": "/usr/local/bin/merlinproject-mcp"
    }
  }
}
    If the file already contains content — whether other MCP servers, preferences, or any other settings — do not overwrite it. Leave all existing top-level keys in place, make sure a "mcpServers" object exists at the top level (create it if necessary), and add the "merlin-project" entry inside it, separated from any sibling entries by a comma. This keeps the file valid JSON. If the file is empty or doesn’t exist yet, paste the snippet above as-is.

Codex

  1. Install the Merlin MCP Server from Main Menu  Merlin Project  Install MCP Server.

  2. Connect Codex to the Merlin Project MCP server by running:

    codex mcp add merlin-project -- /usr/local/bin/merlinproject-mcp

  3. Start Codex, type /mcp, and verify that the Merlin Project MCP server is listed as active.

Antigravity

  1. Install the Merlin MCP Server from Main Menu  Merlin Project  Install MCP Server.

  2. Open an Agent session in Antigravity.

  3. Click the … menu at the top of the side panel and select MCP Servers.

  4. At the top of the MCP Store, click Manage MCP Servers, then View raw config.

  5. Update mcp_config.json with the following entry:

    {
  "mcpServers": {
    "merlin-project": {
      "command": "/usr/local/bin/merlinproject-mcp"
    }
  }
}
    If the file already contains content — whether other MCP servers, preferences, or any other settings — do not overwrite it. Leave all existing top-level keys in place, make sure a "mcpServers" object exists at the top level (create it if necessary), and add the "merlin-project" entry inside it, separated from any sibling entries by a comma. This keeps the file valid JSON. If the file is empty or doesn’t exist yet, paste the snippet above as-is.

  6. Save the file and restart Antigravity to load the MCP server.