Skip to main content
The dotbot MCP server runs as a child process of your AI tool, communicating over stdio. To connect your AI tool to dotbot, add a server entry to the tool’s MCP configuration file pointing at the dotbot-mcp.ps1 script inside your project’s .bot/ directory. Because the path is relative to your project root, your AI tool must be launched from the project directory for the server to start correctly.

​
Prerequisites

Before adding the MCP configuration, make sure you have:
  • Run dotbot init in your project to create the .bot/ directory and generate dotbot-mcp.ps1
  • PowerShell 7 or later (pwsh) installed and available on your PATH
  • The powershell-yaml module installed (Install-Module powershell-yaml -Scope CurrentUser)
Without running dotbot init first, the path .bot/systems/mcp/dotbot-mcp.ps1 will not exist and your AI tool will fail to start the server.

​
Server configuration block

The core configuration is the same regardless of which AI tool you are using: 
{
  "mcpServers": {
    "dotbot": {
      "command": "pwsh",
      "args": ["-NoProfile", "-File", ".bot/systems/mcp/dotbot-mcp.ps1"]
    }
  }
}
Add this block to your AI tool’s MCP configuration file as described in the sections below.

​
Adding the configuration to your AI tool

Open the Claude Desktop configuration file and add the mcpServers block.macOS / Linux:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Full example:
{
  "mcpServers": {
    "dotbot": {
      "command": "pwsh",
      "args": ["-NoProfile", "-File", ".bot/systems/mcp/dotbot-mcp.ps1"]
    }
  }
}
Restart Claude Desktop after saving. The dotbot tools appear in the tool picker when you open a project conversation.

​
Project root requirement

The MCP server auto-detects the project root by walking up the directory tree from its own script location until it finds a .git folder. This has two consequences:
  • Your AI tool’s working directory must be set to a path within the project directory tree when it launches the server.
  • If the server cannot find a .git folder in any parent directory, it exits with a fatal error: FATAL: Could not auto-detect project root.
Do not copy the .bot/ directory to a location outside the git repository. The server relies on .git being present in a parent directory to locate project state files.

​
Verifying the connection

After adding the configuration, ask your AI tool to list the available dotbot tools. You should see all 33 built-in tools, plus any workflow-specific tools installed in your project.
1

Ask for the tool list

In your AI tool, send a message such as: “List the available dotbot MCP tools.” The tool picker or response should show tools like task_create, task_get_next, decision_list, and so on.
2

Check for startup errors

If the tool list is empty or the server fails to start, verify the following:
  • pwsh (PowerShell 7+) is on your PATH — run pwsh --version to confirm
  • dotbot init has been run and .bot/systems/mcp/dotbot-mcp.ps1 exists
  • The powershell-yaml module is installed (Install-Module powershell-yaml -Scope CurrentUser)
3

Confirm the working directory

Make sure your AI tool is launched from within the project directory. If the server logs FATAL: Could not auto-detect project root, the working directory is outside the git repository tree.