Calq

Calq MCP is a server that handles time tracking, AI-powered memory, and team collaboration for your projects. It connects with a client app to let you log work, search memories semantically, manage clients and projects, and share data across your team. It uses a PostgreSQL database for structured data, ChromaDB for vector search, and Voyage AI to generate embeddings for memories and entries.

How to use

You interact with Calq MCP through an MCP client to perform time tracking, memory capture, project management, and team collaboration. Start a timer for a project, log manual time, store personal or shared memories linked to projects or clients, and review unbilled time by client or project. Use the memory search to find notes by meaning, not just keywords, and grant access levels so admins and members see only what they should.

How to install

Prerequisites you need before installing Calq MCP:

• Node.js 20+
• PostgreSQL — relational database for structured data
• ChromaDB — vector database for semantic search
• Voyage AI API key — for embeddings
• GitHub OAuth App — for user authentication

Option 1: Docker Compose (Recommended) This automatically sets up Calq MCP, 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 This option runs everything locally without Docker, suitable for development or testing:

# 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 to customize your Calq MCP setup are shown below. Create a .env file and populate the values you need.

DATABASE_URL=postgres://calq:calq@localhost:5432/calq
VOYAGE_API_KEY=YOUR_VOYAGE_API_KEY
CHROMA_URL=http://localhost:8000
GITHUB_CLIENT_ID=YOUR_GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET=YOUR_GITHUB_CLIENT_SECRET
MCP_PORT=3000
OAUTH_CALLBACK_URL=http://localhost:3000/oauth/callback

GitHub OAuth setup

To enable GitHub authentication, create a GitHub OAuth App and configure the client ID and secret in your environment. Then ensure the callback URL matches the one you configure.

Claude Desktop configuration

If you use Claude Desktop for quick captures, add Calq MCP as a server in Claude Desktop’s config to enable GitHub authentication flows.

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

Available tools

commit

Log time with a 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

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

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

add_client

Add a new client

list_clients

List all clients

configure_project

Create/update project with client and hourly rate

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