Flock MCP Server

An MCP (Model Context Protocol) server that lets you query and manage your Flock todos and goals from Claude Desktop or other MCP-compatible clients.

Quick Install

1. Get your API token from Flock Account Settings
2. Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "flock": {
      "command": "npx",
      "args": ["-y", "flock-mcp-server"],
      "env": {
        "FLOCK_API_TOKEN": "your_token_here"
      }
    }
  }
}

3. Restart Claude Desktop

That's it! Ask Claude "What's on my todo list?" to get started.

Features

Todo Management

• list_todos - List your todos (today, tomorrow, or inbox)
• add_todo - Create a new todo with optional goal assignment
• complete_todo - Mark a todo as complete
• uncomplete_todo - Mark a todo as incomplete
• get_history - Get your todo history for past days

Goals

• list_goals - List all your active goals with stats
• get_goal - Get details about a specific goal

Reviews & Analytics

• get_weekly_reviews - Get weekly stats and review notes
• get_monthly_review - Get monthly review with week-by-week breakdown
• get_yearly_review - Get year-in-review stats and patterns

Prerequisites

• Node.js 18 or later
• A Flock account with an API token

Installation

1. Get your API token

1. Log in to Flock
2. Go to Account Settings (click your avatar, then "My Account")
3. Scroll to the API Token section
4. Copy your token

2. Build the MCP server

From the mcp-server directory:

npm install
npm run build

3. Configure Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the Flock server configuration:

{
  "mcpServers": {
    "flock": {
      "command": "node",
      "args": ["/absolute/path/to/flock/mcp-server/dist/index.js"],
      "env": {
        "FLOCK_API_URL": "https://www.flockwith.me",
        "FLOCK_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Replace:

• /absolute/path/to/flock/mcp-server with the actual path to this directory
• your_api_token_here with your Flock API token
• For local development, change FLOCK_API_URL to http://localhost:3000

4. Restart Claude Desktop

Quit and reopen Claude Desktop for the changes to take effect.

Usage

Once configured, you can ask Claude to interact with your Flock data:

• "What's on my todo list today?"
• "Add 'review PR' to my todos for tomorrow"
• "Show me my goals"
• "Complete todo 123"
• "Add 'write tests' to inbox"
• "What have I done for the 'work' goal?"

Development

Running locally

# Install dependencies
npm install

# Build
npm run build

# Run with environment variables (local dev)
FLOCK_API_URL=http://localhost:3000 FLOCK_API_TOKEN=your_token node dist/index.js

# Or for production
FLOCK_API_URL=https://www.flockwith.me FLOCK_API_TOKEN=your_token node dist/index.js

Watch mode

npm run dev

This rebuilds on file changes.

API Endpoints Used

The MCP server calls these Flock API endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | /api/v1/user | GET | Get current user info | | /api/v1/todos?scope=today\|tomorrow\|inbox | GET | List todos | | /api/v1/todos | POST | Create a todo | | /api/v1/todos/:id/complete | PATCH | Mark todo complete | | /api/v1/todos/:id/uncomplete | PATCH | Mark todo incomplete | | /api/v1/todos/history | GET | Get todo history | | /api/v1/goals | GET | List goals | | /api/v1/goals/:id | GET | Get goal details | | /api/v1/weekly_reviews | GET | Get weekly review stats | | /api/v1/monthly_reviews/:year/:month | GET | Get monthly review stats | | /api/v1/yearly_reviews/:year | GET | Get yearly review stats |

All endpoints require Bearer token authentication.

Troubleshooting

"FLOCK_API_TOKEN environment variable is required"

Make sure your Claude Desktop config includes the env section with FLOCK_API_TOKEN.

"401 Unauthorized"

Your API token may be invalid. Go to Flock Account Settings and regenerate it.

Server not appearing in Claude Desktop

1. Make sure the path to dist/index.js is absolute (not relative)
2. Make sure you've built the project (npm run build)
3. Restart Claude Desktop completely (quit and reopen)

Connection refused

Make sure your Flock server is running at the URL specified in FLOCK_API_URL.