Traggo MCP Server

An MCP server that lets AI assistants track time in

Traggo. It proxies MCP tool calls to a Traggo instance's GraphQL API,

and ships a small web UI for obtaining the access token you authenticate with.

How it works

The server has two surfaces:

1. Web login (`/login`) — you sign in with your Traggo username and password and get back a

Traggo *device token*. This is a thin wrapper over Traggo's `login` GraphQL mutation; the token

is shown on screen for you to copy.

2. MCP endpoint (`/mcp`) — your MCP client connects here and sends the token as a

`Authorization: Bearer ` header. Each tool call is translated into a Traggo GraphQL

request (sent upstream as `Authorization: traggo `, the scheme Traggo expects).

The server is stateless — it stores nothing. The Traggo token is the entire auth state.

┌─────────────┐   Bearer    ┌──────────────┐   traggo    ┌────────────┐
 MCP client │  POST /mcp  │ ─────────────────► │ traggo-mcp   │ ─────────────────► │   Traggo   │
            └─────────────┘                    │ (this server)│   GraphQL          │  instance  │
                                               └──────────────┘                    └────────────┘
   browser  ── GET/POST /login ──────────────► returns a device token to copy

Tools

Tags are key/value pairs (e.g. `{"key": "project", "value": "traggo"}`). Times are RFC3339

(e.g. `2026-06-28T09:00:00Z`).

Running

The server needs one environment variable: `TRAGGO_URL`, the base URL of your Traggo instance

(no trailing slash).

export TRAGGO_URL=https://traggo.example.com
go run ./cmd/server

It listens on `:8080`. Open to get a token, then point your MCP

client at `http://localhost:8080/mcp`.

Connecting an MCP client

Use a streamable-HTTP MCP transport pointed at `/mcp`, with the token as a bearer credential. For

example, in a client that supports HTTP MCP servers:

{
  "mcpServers": {
    "traggo": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer " }
    }
  }
}

Development

Prerequisites

• Go 1.26+
• templ — `go install github.com/a-h/templ/cmd/templ@latest` (HTML templating)
• Bun — runs the Tailwind CLI via `bunx`
• air — `go install github.com/air-verse/air@latest` (hot reload, optional)
• Dagger — only needed to build/publish the container image

Hot-reload dev loop

export TRAGGO_URL=https://traggo.example.com
air

`air` (configured in `.air.toml`) regenerates templates and CSS, rebuilds, and serves with live

reload on (proxying the app on `:8080`).

Building assets manually

If you're not using `air`:

templ generate                                          # .templ → _templ.go
bunx @tailwindcss/cli -i ./app.css -o assets/output.css # build CSS
go run ./cmd/server

Project layout

cmd/server/        Entry point: route wiring, starts the HTTP server
internal/
  auth/            Web login flow → Traggo device token
  mcp/             MCP server: tool registration + bearer-token middleware
  traggo/          GraphQL client for the Traggo API (all timer/timespan/tag ops)
views/             templ components and pages for the web UI
assets/            Static files (generated CSS, images)
.dagger/           Dagger module for building & publishing the container image

Building & publishing the image

The container image is built with Dagger — a multi-stage build (Go compile

on `golang:1.26`, runtime on `wolfi-base`) that publishes to a container registry. Registry,

credentials and image name are all parameters:

dagger call build \
  --source . \
  --registry registry.example.com \
  --username you@example.com \
  --registry-password env:REGISTRY_PASSWORD \
  --image traggo-mcp:latest

`--source` defaults to `.` and `--image` defaults to `traggo-mcp:latest`. The function returns the

published image reference.

Contributing

Contributions are welcome. To get started:

1. Fork and clone the repo.

2. Install the prerequisites above and run `air` (or the manual build steps) against a Traggo

instance you control.

3. Make your change. If you touch a `.templ` file, run `templ generate`. If you add or change a

dependency, run `go mod tidy`.

4. Make sure `go build ./...` and `go vet ./...` pass.

5. Open a pull request describing the change.

When adding a new tool, the pattern is:

• Define the input/output types in `internal/traggo/types.go` (use `jsonschema` struct tags so the

MCP schema is descriptive).

• Add the operation method to `internal/traggo/service.go` (it goes through the shared `execute`

helper for auth and error handling).

• Register the tool in `internal/mcp/server.go`.

The Traggo GraphQL schema is the source of truth for available operations and field names.