Control Focuh from Claude Desktop with MCP

If you use Claude Desktop as your AI assistant, you can control Focuh directly from your conversations. Start focus sessions, add tasks, check your current session status — 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.

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 five tools:

Tool	What It Does
startFocusSession	Starts a focus session with a specified duration
stopFocusSession	Stops the currently running focus session
getActiveFocusSession	Checks if a session is active and how much time is left
addTask	Creates a new task on today's task board
listTasks	Lists your tasks for today

These tools work together. You can have a conversation with Claude about your workday, and it can set up your focus session and tasks 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: Find Your Convex URL

Open Focuh and go to Settings. Your Convex deployment URL is shown in the app, or you can find it in your Focuh project's .env.local file. It looks like https://your-deployment.convex.cloud.

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": {
        "CONVEX_URL": "https://your-deployment.convex.cloud"
      }
    }
  }
}

Replace https://your-deployment.convex.cloud with your actual Convex URL.

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 focus on writing the Q2 report this morning. Add it as a task and start a 90-minute focus session."

Claude will:

1. Call addTask to create "Write Q2 report" on today's board
2. Call startFocusSession with a 90-minute duration
3. Focuh activates website blocking and starts the timer

Checking Your Session

"How much time do I have left in my current focus session?"

Claude calls getActiveFocusSession and tells you the remaining time, what task you're working on, and when the session will end.

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."

Claude calls addTask four times, creating each task on your Focuh board. When you're ready to focus, they're already organized and waiting.

Session Management

"I finished early. Stop my focus session and show me what's left on my task list."

Claude calls stopFocusSession to end blocking, then listTasks to show your remaining tasks for the day.

Why This Matters

The point isn't that typing "start a focus session" to Claude is faster than clicking a button in Focuh. It's that focus session management 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 set up your focus environment as part of that flow. You don't context-switch from a planning conversation to a separate app to manually configure your session. 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 focus sessions 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" errors: Verify your Convex URL is correct and that your Focuh account is active. The MCP server needs to reach the Convex backend.

Tasks appear but focus session doesn't start blocking: The MCP server creates the session in the database, but blocking requires the Focuh desktop app to be running on your Mac. Make sure Focuh is open and signed in.

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