hmesfin/super-productivity-mcp-server

SuperProductivity MCP Server

MCP (Model Context Protocol) server that integrates SuperProductivity task management with Claude Code.

What is an MCP Server?

MCP servers are local processes that run on your machine, not remote services. They extend Claude Code with access to external data and APIs through a standardized protocol. This MCP server gives Claude Code read access to your SuperProductivity tasks.

Key Points:

• Runs locally via stdio (standard input/output)
• No deployment or hosting required
• Automatically managed by Claude Code
• Secure local access to your SuperProductivity data

Features

Current:

• ✅ List tasks with filtering (by project, completion status)
• ✅ Get individual task details
• ✅ List all projects
• ✅ Search tasks by title/tags

Planned:

• 🔜 Write operations (create/update/complete tasks)
• 🔜 Advanced features (project planning, smart workflows)

Requirements

• Python 3.13+
• SuperProductivity with sync file at ~/GoogleDrive/SuperProductivity/__meta_

Installation

# Install with uv
uv pip install -e .

# Or with pip
pip install -e .

# For development
pip install -e ".[dev]"

Installation for Claude Code

1. Clone and Install

# Clone the repository
git clone https://github.com/yourusername/sp-mcp.git ~/projects/sp-mcp
cd ~/projects/sp-mcp

# Install with uv (recommended)
uv pip install -e .

# Or with pip
pip install -e .

2. Configure Claude Code

Add to your ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "super-productivity": {
      "type": "stdio",
      "command": "python",
      "args": ["/home/yourusername/projects/sp-mcp/src/server.py"],
      "env": {
        "SP_META_PATH": "/home/yourusername/GoogleDrive/SuperProductivity/__meta_",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Adjust paths:

• Replace /home/yourusername/ with your actual home directory
• Update SP_META_PATH to your SuperProductivity sync file location

3. Restart Claude Code

Claude Code will automatically start the MCP server when it launches. You don't need to run it manually!

Usage

Once configured, Claude Code can access your SuperProductivity tasks:

You: "Show me my tasks for the django-project"
Claude: [Uses mcp__sp-mcp__list_tasks_tool automatically]

You: "What's the status of task abc123?"
Claude: [Uses mcp__sp-mcp__get_task_tool automatically]

Development

Running Tests

# Run tests
pytest

# Run tests with coverage
pytest --cov=src --cov-report=html

# Lint and format
ruff check src/ tests/
ruff format src/ tests/

Testing the Server Manually

For development and debugging, you can run the server standalone:

# Set environment variable
export SP_META_PATH=~/GoogleDrive/SuperProductivity/__meta_

# Run the server
python src/server.py

# The server will start and wait for stdio input from an MCP client

Note: In production, Claude Code manages the server lifecycle automatically.

Architecture

Project Structure

• src/models.py - Pydantic models for Task, Project, Tag
• src/sp_parser.py - Parse SuperProductivity __meta_ JSON file
• src/server.py - FastMCP server with MCP tools

How It Works

┌─────────────────┐
│  Claude Code    │  (MCP Client)
└────────┬────────┘
         │ stdio (stdin/stdout)
         │
┌────────▼────────┐
│   sp-mcp        │  (This MCP Server)
│   server.py     │  Runs locally on your machine
└────────┬────────┘
         │ File read
         │
┌────────▼────────┐
│ SuperProductivity│
│   __meta_ file  │  Your local task database
└─────────────────┘

The MCP server:

1. Reads your SuperProductivity sync file (__meta_)
2. Exposes tools (list_tasks, get_task, etc.) via MCP protocol
3. Claude Code calls these tools automatically when relevant