tablero

README

Tablero

Unified task aggregator for AI coding agents. One MCP server that connects Linear, Taiga and OpenProject so you can list, search, create, update, and read tasks — and Linear documents — across all your workspaces without leaving the terminal.

Agent (Claude Code / Cursor / Cline / OpenCode / any MCP client)
    | MCP stdio
Tablero (single Go binary)
    |
    +---> Linear GraphQL API (any number of workspaces)
    +---> Taiga REST API (any number of instances, self-hosted or cloud)
    +---> OpenProject REST API v3 (any number of instances, self-hosted or cloud)

Features

• Tasks across workspaces — list, get, create, update, search issues from multiple Linear workspaces, Taiga instances, and OpenProject instances at once.
• Linear documents CRUD — read and write Linear docs (markdown) from your agent.
• Team vs Project aware — Linear's two-level hierarchy (teams + projects) is exposed correctly; filter tasks or docs by either.
• Interactive CLI — tablero config add linear / add taiga / add openproject walks you through setup, validates the connection, and writes the config for you.
• Graceful degradation — if one provider is unreachable (VPN down, etc.) the others still work; failures surface as warnings, not hard errors.
• Single binary — one Go executable, zero runtime dependencies.

Quick start

Three steps. The whole thing takes about two minutes if you already have a Linear API key ready.

1. Install the binary

With Go (simplest — always picks the latest release):

go install github.com/Gabriel100201/tablero/cmd/tablero@latest

Make sure $(go env GOPATH)/bin — typically ~/go/bin on Linux/macOS or %USERPROFILE%\go\bin on Windows — is on your PATH.

Without Go: download the archive for your OS from the latest release, extract it, and put tablero (or tablero.exe) somewhere on your PATH. Full details and checksum verification in the Install section.

Verify:

tablero version

2. Add your first workspace

tablero config add linear

You'll be prompted for:

• A friendly name (e.g. work) — this is how you'll reference the workspace from agent tools
• Your Linear API key (input is hidden) — get one at Linear → Settings → API → Personal API keys → Create key

Tablero validates the key against Linear before saving. If it's valid, you'll see ✓ Connection OK and the config is written to ~/.tablero/config.yaml with mode 0600.

Repeat tablero config add linear for every additional Linear workspace, or tablero config add taiga for a Taiga instance. Then verify everything works:

tablero config list   # shows all providers with secrets masked
tablero config test   # pings each provider

3. Connect to your AI agent

Claude Code:

claude mcp add --transport stdio tablero -- tablero mcp

Then reload the MCP connection inside Claude Code — run /mcp and reconnect tablero (or just restart the session). Claude Code picks up the 13 tools automatically.

Cursor / Cline / Windsurf / any other MCP client: add a stdio server with command tablero and args ["mcp"] — see Register with your AI agent for exact JSON snippets.

That's it — ask your agent "what do I have assigned in Linear today?" and it will call tasks_list assigned=true on its own.

Install

Option A — Download a pre-built binary (no Go needed)

Grab the archive for your OS and architecture from the latest release:

• tablero_<version>_linux_amd64.tar.gz
• tablero_<version>_linux_arm64.tar.gz
• tablero_<version>_darwin_amd64.tar.gz — macOS Intel
• tablero_<version>_darwin_arm64.tar.gz — macOS Apple Silicon
• tablero_<version>_windows_amd64.zip

Extract the tablero (or tablero.exe) binary and put it somewhere on your PATH.

# example for Linux amd64
curl -sL https://github.com/Gabriel100201/tablero/releases/latest/download/tablero_<version>_linux_amd64.tar.gz | tar -xz
sudo mv tablero /usr/local/bin/

Each release also ships checksums.txt (SHA-256) so you can verify the download.

Option B — go install

go install github.com/Gabriel100201/tablero/cmd/tablero@latest

The binary lands in $(go env GOPATH)/bin (typically ~/go/bin on Unix, %USERPROFILE%\go\bin on Windows). Make sure that directory is on your PATH.

Option C — Build from source

git clone https://github.com/Gabriel100201/tablero.git
cd tablero
go install ./cmd/tablero/

Verify

tablero version
tablero help

Quick start — interactive setup

The fastest path is the built-in CLI:

# Add a Linear workspace (prompts for a friendly name + API key; validates the key)
tablero config add linear

# Add a Taiga instance (prompts for URL + username + password; validates via auth)
tablero config add taiga

# Add an OpenProject instance (prompts for URL + API key; validates via /users/me)
tablero config add openproject

# Add as many as you want — e.g. multiple Linear workspaces for work and personal
tablero config add linear

# Inspect what's configured (secrets are masked)
tablero config list

# Verify every provider is reachable
tablero config test

# Remove one
tablero config remove <name>

# Print the config file path
tablero config path

The config is saved to ~/.tablero/config.yaml (or $TABLERO_CONFIG if set) with mode 0600 — owner read/write only — because it contains API keys and passwords.

Manual configuration (optional)

If you prefer editing YAML by hand, copy config.example.yaml to ~/.tablero/config.yaml and fill it in:

providers:
  - name: work           # any unique label — you'll use it to reference this provider
    type: linear
    api_key: "lin_api_..."

  - name: personal
    type: linear
    api_key: "lin_api_..."

  - name: team-taiga
    type: taiga
    url: "https://taiga.example.com"
    username: "myuser"
    password: "mypassword"

  - name: my-openproject
    type: openproject
    url: "https://openproject.example.com"
    api_key: "opapi-..."

Field	Required for	Description
name	all	Unique identifier — an arbitrary label you choose
type	all	linear, taiga or openproject
api_key	linear, openproject	Linear personal API key, or OpenProject API token (My account → Access tokens → API)
url	taiga, openproject	Base URL of the Taiga / OpenProject instance
username	taiga	Taiga username
password	taiga	Taiga password

Override the config path with the TABLERO_CONFIG environment variable.

Register with your AI agent

Claude Code

claude mcp add --transport stdio tablero -- tablero mcp

Windows gotcha: claude mcp add with absolute paths can strip backslashes. Either use just tablero (if it's on your PATH), or after running the command verify the path in ~/.claude.json has proper backslashes (C:\\Users\\...) and fix it manually if needed.

OpenCode

Add to ~/.config/opencode/config.json:

{
  "mcpServers": {
    "tablero": {
      "command": "tablero",
      "args": ["mcp"]
    }
  }
}

Any MCP client

Tablero uses stdio transport. Configure with:

• Command: tablero (or full path to the binary)
• Args: ["mcp"]

MCP Tools

Tasks

Tool	Read-only	Description
tasks_list	✓	List open tasks across all providers. By default returns all open tasks; set assigned=true to see only your own.
tasks_get	✓	Full detail of a task by identifier (description, comments, labels)
tasks_create	—	Create a task in a specific provider/project
tasks_update	—	Update status, title, priority, description
tasks_search	✓	Keyword search across titles and descriptions
tasks_projects	✓	List all teams and projects (Linear exposes both; Taiga and OpenProject only projects)
tasks_states	✓	List valid workflow states for a project (use before tasks_update)

Documents (Linear only)

Tool	Read-only	Description
docs_list	✓	List Linear docs; filter by provider, project, or title substring. Project filter also accepts a team name (returns union across its projects).
docs_get	✓	Fetch a doc by slug or UUID — returns the full markdown body
docs_create	—	Create a doc inside a Linear project
docs_update	—	Update title, content, icon, or color
docs_delete	— (destructive)	Permanently delete a doc
docs_search	✓	Native Linear document search

Identifier format

• Linear tasks: issue key, e.g. ABC-42
• Linear docs: slugId (from URL) or UUID
• Taiga user stories: <providerName>:us:<id>, e.g. work:us:234
• Taiga tasks: <providerName>:task:<id>, e.g. work:task:56
• OpenProject work packages: <providerName>:wp:<id>, e.g. work:wp:1234

Project model (Linear)

Linear has two levels:

• Team — e.g. name "Acme" with key ACME, groups all issues with prefix ACME-xx
• Project — e.g. "Website Redesign", a logical grouping of issues inside a team

tasks_projects lists both, and the Kind column tells them apart. The project filter on tasks_list and docs_list matches either level — pass a team name/key to see everything in a team, or a project name to narrow down.

OpenProject notes

• Tasks map to work packages; tasks_create defaults to the Task type (or the project's first type if none is named Task).
• Workflow statuses are defined instance-wide in OpenProject, so tasks_states returns the same set regardless of which project you pass.
• Documents are not supported (the docs_* tools apply to Linear only).

Graceful degradation

If a provider is unreachable (e.g. Taiga behind a VPN that's disconnected), Tablero returns results from the healthy providers with a warning. It does not fail the whole call.

Security

The config file contains API keys and passwords. Tablero writes it with permissions 0600 so only the owner can read it. On shared machines, make sure your home directory has appropriate protection.

Never commit your config to a public repository. This repo's .gitignore excludes config.yaml by default.

Environment variables

Variable	Description	Default
TABLERO_CONFIG	Config file path	~/.tablero/config.yaml

Requirements

• Go 1.25+ to build from source (the CLI depends on golang.org/x/term for hidden password prompts)
• No runtime dependencies

Contributing

Bug reports, feature requests, and pull requests are welcome. See CONTRIBUTING.md for the development setup, commit convention, and PR flow. Maintainers cutting a release should follow RELEASING.md.

License

MIT