Control Focuh from Claude Desktop with MCP

If you use Claude Desktop as your AI assistant, you can control Focuh directly from your conversations. Plan your day, add and reshuffle tasks, check your goals and focus stats — all without switching windows.

This works through MCP (Model Context Protocol), an open standard that lets AI assistants interact with external tools. Setup takes about 5 minutes.

The fast way: open Focuh, go to Preferences → MCP Server, and click Copy setup prompt. Paste that prompt into Claude Code, Cursor, or any agent that can edit files, and it does the rest — it works out which client it's running in, writes the config with your credentials already filled in, and verifies the connection. If you'd rather do it by hand, the manual steps are below.

What Is MCP?

Model Context Protocol is an open protocol developed by Anthropic that gives AI assistants the ability to use external tools. Instead of being limited to text conversations, an AI assistant with MCP can call functions in other applications — read data, trigger actions, and interact with your tools.

Think of it like giving Claude hands. Without MCP, you tell Claude about your tasks and it gives you advice. With MCP, you tell Claude to add a task and it actually adds the task to Focuh.

What Claude Can Do with Focuh

The Focuh MCP server exposes 14 tools, grouped by what they touch:

Group	Tools	What They Do
Tasks	get_tasks, create_tasks, update_tasks, delete_tasks	Read today and tomorrow, then create, edit, or delete tasks in bulk — title, date, priority, estimate, completion, time slot
Subtasks	get_subtasks, reorder_subtasks	Break a task down and set the order you'll work through it
Loops	get_loops, pull_loops	Undated recurring intentions, and pulling them onto a specific day
Calendar	get_calendar	Events plus scheduled and unscheduled tasks for a date, so Claude can schedule around meetings
Goals	get_goals, create_goal, update_goal, delete_goal	Goals by horizon — week, month, year, decade
Stats	get_focus_stats	Focus minutes today and this week, your streak, completion rates

These tools work together. You can have a conversation with Claude about your workday, and it can lay out your tasks and schedule as part of that conversation.

Setup: 5 Minutes

Prerequisites

• Focuh installed and signed in on your Mac
• Claude Desktop installed
• Node.js installed (v18 or later)

Step 1: Get Your Credentials

Open Focuh and go to Preferences → MCP Server. Click Generate API Key and copy the key — it's only shown once. The same screen shows your Convex site URL, which looks like https://your-deployment.convex.site. You need both values.

Step 2: Configure Claude Desktop

Open Claude Desktop's configuration file. On macOS, it's at:

~/Library/Application Support/Claude/claude_desktop_config.json

Add the Focuh MCP server to the mcpServers section:

{
  "mcpServers": {
    "focuh": {
      "command": "npx",
      "args": ["-y", "@focuh/mcp-server"],
      "env": {
        "FOCUH_API_KEY": "focuh_your_key_here",
        "FOCUH_CONVEX_URL": "https://your-deployment.convex.site"
      }
    }
  }
}

Replace both placeholders with the values from Preferences → MCP Server. If the file already lists other servers, merge the focuh entry into the existing mcpServers object instead of overwriting it.

Using Claude Code instead? One line does the whole thing:

claude mcp add focuh -s user -e FOCUH_API_KEY=<key> -e FOCUH_CONVEX_URL=<url> -- npx -y @focuh/mcp-server

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop. You should see a hammer icon in the chat input area indicating that MCP tools are available. Click it to verify the Focuh tools are listed.

That's it. You can now control Focuh from Claude.

Example Workflows

Morning Planning

"I need to write the Q2 report this morning. Add it as a 90-minute task, break it into sections, and put it in a free slot before lunch."

Claude will:

1. Call get_calendar to see what's already booked today
2. Call create_tasks to create "Write Q2 report" with its subtasks nested underneath
3. Call update_tasks to drop it into a slot that doesn't collide with your meetings

Reshuffling the Day

"I lost the morning. Move everything I haven't started to tomorrow, except the Q2 report — that stays and becomes critical."

Claude calls get_tasks to see what's on the board, then one update_tasks call moves the dates and bumps the priority in a single pass. Nothing is deleted and recreated, so subtasks, focus history, and goal links survive.

Quick Task Dump

"Add these tasks for today: review Sarah's PR, update the API docs, fix the login redirect bug, and send the deployment checklist to the team."

One create_tasks call creates all four on your Focuh board. When you're ready to focus, they're already organized and waiting.

Weekly Review

"How much focus time did I log this week, and how are my month goals tracking?"

Claude calls get_focus_stats for your minutes, streak, and completion rate, then get_goals for the month horizon — and can update a goal's bottleneck note with update_goal while you're talking it through.

Why This Matters

The point isn't that typing "add a task" to Claude is faster than clicking a button in Focuh. It's that planning your day becomes part of a larger conversation.

When you're talking to Claude about your work — planning your day, breaking down a project, debugging a problem — the AI can shape your board as part of that flow. You don't context-switch from a planning conversation to a separate app to type it all in again. The conversation and the action happen in the same place.

This is especially useful for people who use Claude as a daily thinking partner. Your tasks and goals become part of the conversation about what you're working on and why, rather than a separate manual step you have to remember.

Troubleshooting

Claude doesn't show the hammer icon: Make sure the configuration file is valid JSON and the file path is correct. Restart Claude Desktop after any config changes.

"Connection refused" or "unauthorized" errors: Check that FOCUH_CONVEX_URL is the .convex.site URL from Preferences → MCP Server, not a .convex.cloud one, and that FOCUH_API_KEY is the current key. Generating a new key invalidates the old one, so any config still holding the old key will fail.

No terminal, no config file? Claude.ai and ChatGPT can't run a local server, so connect them to Focuh's hosted endpoint at https://www.focuh.com/api/mcp instead — Claude.ai under Settings → Connectors → Add custom connector, ChatGPT under Settings → Connectors → Advanced → Developer mode. Both use OAuth, so there's no key to paste.

Node.js errors: Ensure you have Node.js v18 or later installed. Run node --version in Terminal to check.