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

``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

$3

- 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

$3

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

$3

- 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

$3

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

$3

From the mcp-server directory:

`bash
npm install
npm run build
`

$3

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:

`json
{
"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

$3

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

$3

`bash


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
`

$3

`bash
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

$3

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

$3

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

$3

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)

$3

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