Getting Started

Installation

One-liner Install

curl -fsSL https://raw.githubusercontent.com/gnodux/adb-link/main/scripts/install-adb-link.sh | bash

This installs the latest release to ~/.adb-link/ and creates a symlink at ~/.local/bin/adb-link.

Build from Source

git clone https://github.com/gnodux/adb-link.git
cd adb-link
make build
# Binary: bin/adb-link

Requirements

Initial Configuration

Configuration files live in ~/.adb-link/conf/ by default (override via ADB_LINK_CONFIG_DIR).

mkdir -p ~/.adb-link/conf
cp conf/mcp_stdio.yaml.example ~/.adb-link/conf/mcp_stdio.yaml

Add a Datasource

Create ~/.adb-link/conf/datasource.yaml:

kind: datasource
name: my-postgres
type: postgresql
description: "Production PostgreSQL"
connection:
  host: 127.0.0.1
  port: 5432
  username: app_user
  password: ${PG_PASSWORD}
  default_database: mydb
options:
  pool_size: 10

Add Authentication

Create ~/.adb-link/conf/auth.yaml:

kind: users
users:
  - name: admin
    api_key: "your-secret-api-key"
    group: admin
  - name: mcp_stdio_user
    group: mcp
    description: "Default user for MCP stdio transport"

Set Permissions

Create ~/.adb-link/conf/permission.yaml:

kind: permission
groups: ["admin"]
enable: true
rules:
  - datasource: "*"
    databases: ["*"]
    tables: ["*"]
    fields: ["*"]
tools: ["*"]

Running

# API + MCP HTTP on a single port (default :8000)
adb-link run-all

# API only
adb-link run-api

# MCP over stdio (for IDE/agent integration)
adb-link run-mcp

Verify

curl http://localhost:8000/api/health
# {"status":"ok"}

MCP Integration

Claude Desktop / Cursor

Add to your MCP client configuration (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "adb-link": {
      "command": "adb-link",
      "args": ["run-mcp"]
    }
  }
}

The stdio transport uses mcp_stdio_user as the default identity. Configure permissions for this user in your auth/permission YAML files.

HTTP Transport

For remote or multi-client access:

adb-link run-all  # MCP available at /mcp endpoint

Clients connect to http://host:8000/mcp with Bearer token authentication.

Next Steps