Calq MCP

A Model Context Protocol (MCP) server for time tracking, project management, AI-powered memory, and team collaboration.

Features

⏱️ Time Tracking

• Timer system - Start/stop timers for real-time tracking
• Manual logging - Log time with backdating support
• Billing - Mark entries as billable/billed, track unbilled time

🧠 AI-Powered Memory

• Semantic search - Find memories and entries by meaning, not just keywords
• Personal & shared - Keep notes private or share with your team
• Project/client linking - Associate memories with specific projects or clients
• Vector storage - Powered by ChromaDB and Voyage AI embeddings

👥 Team Collaboration

• GitHub OAuth - Authenticate team members via GitHub (integrated into MCP flow)
• Role-based access - Admin and member roles
• Per-user data - Timers and entries are user-scoped

📊 Project & Client Management

• Clients - Manage client information
• Projects - Link projects to clients with hourly rates
• Invoice summaries - Get unbilled time grouped by client with calculated values

Prerequisites

• Node.js 20+
• PostgreSQL - Relational database for structured data
• ChromaDB - Vector database for semantic search
• Voyage AI API key - For generating embeddings
• GitHub OAuth App - For user authentication

Installation

Option 1: Docker Compose (Recommended)

This automatically sets up Calq, PostgreSQL, and ChromaDB:

git clone https://github.com/Calq-dev/calq-mcp.git
cd calq-mcp

# Copy and configure environment
cp .env.example .env
# Edit .env with your API keys

# Start services (uses default ports 3000 and 8000)
docker compose up -d

# Or with custom ports
MCP_PORT=3001 CHROMA_PORT=8001 docker compose up -d

Services:

• Calq MCP: http://localhost:${MCP_PORT}/mcp (default: 3000)
• PostgreSQL: Internal to Docker (port 5432)
• ChromaDB: http://localhost:${CHROMA_PORT} (default: 8000, internal to Docker)

Option 2: Local Development

# 1. Start PostgreSQL and ChromaDB (required)
docker run -d --name postgres -p 5432:5432 \
  -e POSTGRES_USER=calq -e POSTGRES_PASSWORD=calq -e POSTGRES_DB=calq \
  postgres:16-alpine

docker run -d --name chromadb -p 8000:8000 chromadb/chroma:latest

# 2. Clone and install
git clone https://github.com/Calq-dev/calq-mcp.git
cd calq-mcp
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env with your API keys

# 4. Push database schema
npm run db:push

# 5. Start the server
node src/index.js

Configuration

Environment Variables

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection URL
POSTGRES_PASSWORD	No	PostgreSQL password for Docker (default: calq)
VOYAGE_API_KEY	Yes	Voyage AI API key for embeddings
CHROMA_URL	No	ChromaDB URL (default: http://localhost:8000)
GITHUB_CLIENT_ID	Yes	GitHub OAuth App client ID
GITHUB_CLIENT_SECRET	Yes	GitHub OAuth App client secret
MCP_PORT	No	Server port (default: 3000)
OAUTH_CALLBACK_URL	No	OAuth callback (default: http://localhost:3000/oauth/callback)

Database Management

Calq uses Drizzle ORM with PostgreSQL:

# Generate migrations from schema changes
npm run db:generate

# Apply migrations
npm run db:migrate

# Push schema directly (development)
npm run db:push

# Open Drizzle Studio
npm run db:studio

GitHub OAuth Setup

1. Go to GitHub Developer Settings
2. Click "New OAuth App"
3. Fill in:
   • Application name: Calq
   • Homepage URL: http://localhost:3000
   • Authorization callback URL: http://localhost:3000/oauth/github/callback
4. Copy the Client ID and generate a Client Secret
5. Add both to your .env file

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "calq": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

When you first use Calq, Claude Desktop will open a browser for GitHub authentication.

Tools

Time Tracking

Tool	Description
commit	Log time with message, project, and optional date
start	Start a timer for a project
stop	Stop timer and log the time
timer_status	Check if a timer is running
cancel_timer	Discard timer without logging
delete	Delete a time entry
edit	Modify an existing entry

Summaries

Tool	Description
list_projects	List all projects with total time
list_projects_detailed	Projects with client info and values
get_project_summary	Detailed summary for a project
get_today_summary	Today's time by project
get_weekly_summary	This week's time by day
get_unbilled	Unbilled time summary
get_invoice_summary	Unbilled time by client with values

Memory

Tool	Description
remember	Store a memory (personal/shared, linked to project/client)
idea	Quick capture an idea
recall	Search memories semantically
search_entries	Search time entries semantically
list_memories	List all memories
list_ideas	List all captured ideas
forget	Delete a memory

Clients & Projects

Tool	Description
add_client	Add a new client
list_clients	List all clients
configure_project	Create/update project with client and hourly rate

Users

Tool	Description
whoami	Show current user info
list_users	List all users (admin only)
set_user_role	Change user role (admin only)
team_summary	Team activity summary

Usage Examples

"Start timing the website project"
"Stop - finished the navbar"
"Log 2 hours to API work yesterday: implemented auth"
"Remember: client wants deadline moved to January"
"Recall: what did the client say about deadlines?"
"What's my unbilled time for Acme Corp?"
"Configure project website with client Acme and rate 95"

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude Desktop │────▶│   Calq MCP      │────▶│    ChromaDB     │
│                 │     │  (Port 3000)    │     │  (Port 8000)    │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │   PostgreSQL    │
                        │  (Port 5432)    │
                        └─────────────────┘

• PostgreSQL - Source of truth for structured data (entries, projects, users)
• ChromaDB - Vector store for semantic search (memories, entry embeddings)
• Drizzle ORM - Type-safe database access layer

Data Storage

In Docker, data is persisted via volumes:

• calq-data - Application data
• postgres-data - PostgreSQL database
• chroma-data - ChromaDB embeddings

License

MIT