MCP Server Setup

Pulse includes a Model Context Protocol (MCP) server that lets AI assistants like Claude manage your tasks, habits, reviews, and more through natural conversation.

Prerequisites

Node.js 20+
A Pulse GTD account
An API key (see Authentication)

Installation

The MCP server is included in the Pulse monorepo at services/mcp/. Build it:

cd services/mcp
pnpm install
pnpm build

Configuration

Add the MCP server to your Claude Code project by creating a .mcp.json file in your project root:

{
  "mcpServers": {
    "pulse-gtd": {
      "command": "node",
      "args": ["path/to/pulse-gtd/services/mcp/dist/index.js"],
      "env": {
        "API_BASE_URL": "https://pulsegtd.app",
        "API_TOKEN": "pgtd_your_api_key_here"
      }
    }
  }
}

Replace path/to/pulse-gtd with the actual path to your Pulse GTD repository, and pgtd_your_api_key_here with your API key.

Quick Setup

The MCP server runs locally on your machine via stdio — no network server needed. Just build, configure the path, and restart your AI assistant.

Available Tools

The MCP server exposes 18 tools:

Task Management

Tool	Description
`list_tasks`	List tasks with optional date and completion filters
`create_task`	Create a new task with title, date, urgency, importance
`update_task`	Update task fields
`complete_task`	Mark a task as completed
`delete_task`	Delete a task

Projects

Tool	Description
`list_projects`	List all projects
`create_project`	Create a new project

Habits

Tool	Description
`list_habits`	List all habits
`create_habit`	Create a new habit
`log_habit`	Log a habit completion or skip
`get_habit_streaks`	Get streak data for all habits

Reviews & Analytics

Tool	Description
`list_reviews`	List review entries
`create_review`	Create a weekly or monthly review
`get_dashboard`	Get dashboard statistics

Organization

Tool	Description
`list_buckets`	List life buckets
`list_bottlenecks`	List bottlenecks
`create_bottleneck`	Create a bottleneck

Usage Examples

Once configured, you can interact with Pulse through Claude:

"Create a task called 'Review Q1 metrics' for tomorrow, marked as Important"

"What habits do I have due today?"

"Run my weekly review"

"Show me my dashboard stats"

"Log my morning meditation habit as complete"

Transport

The MCP server uses stdio transport — it communicates via standard input/output. This means it runs locally on your machine and doesn't require a network server.

Environment Variables

Variable	Required	Description
`API_BASE_URL`	Yes	The Pulse API URL (e.g., `https://pulsegtd.app`)
`API_TOKEN`	Yes	Your Pulse API key (starts with `pgtd_`)

Troubleshooting

API Key Security

Never commit your API key to version control. Use environment variables or a .env file that's in your .gitignore.

"Unauthorized" errors: Verify your API key is valid in Settings → API Keys
"Connection refused": Check that API_BASE_URL is correct and the server is running
MCP not loading: Restart Claude Code after adding/modifying .mcp.json
Build errors: Ensure you've run pnpm install and pnpm build in services/mcp/