tanuki-mcp

A high-performance GitLab MCP (Model Context Protocol) server written in Rust with fine-grained access control.

Inspired by zereight/gitlab-mcp.

Features

• 121 GitLab Tools across 20 categories
• Built-in Prompts for issue analysis and MR review workflows
• Resource Access via gitlab:// URI scheme for file reading
• Fine-Grained Access Control with hierarchical overrides
• Two Transport Modes: stdio (Claude Code) and HTTP (Streamable HTTP)
• Real-Time Dashboard for monitoring usage
• Project-Specific Permissions for granular control
• Pattern-Based Rules using regex for allow/deny lists

MCP Capabilities

tanuki-mcp implements the full MCP specification with tools, prompts, and resources.

Prompts

Built-in workflow prompts for common GitLab tasks:

Usage in Claude Code:

Use the analyze_issue prompt for project "group/repo" issue 42

Resources

Read GitLab repository files using the gitlab:// URI scheme:

gitlab://{project}/{file_path}?ref={branch}

Examples:

• gitlab://group%2Fproject/README.md - Default branch
• gitlab://group%2Fproject/src/main.rs?ref=develop - Specific branch

Note: Project path must be URL-encoded (/ → %2F)

Quick Start

Using Docker

# Run with stdio transport
docker run -it --rm \
  -e TANUKI_MCP__GITLAB_URL=https://gitlab.com \
  -e TANUKI_MCP__GITLAB_TOKEN=glpat-xxx \
  tanuki-mcp

# Run with HTTP transport
docker run -d \
  -p 20289:20289 \
  -p 19892:19892 \
  -e TANUKI_MCP__GITLAB_URL=https://gitlab.com \
  -e TANUKI_MCP__GITLAB_TOKEN=glpat-xxx \
  tanuki-mcp --http

Using Pre-Built Binary

# Download from releases
curl -LO https://github.com/tarfu/tanuki-mcp/releases/latest/download/tanuki-mcp
chmod +x tanuki-mcp

# Set token and run
export TANUKI_MCP__GITLAB_TOKEN=glpat-xxx
./tanuki-mcp

Using cargo-binstall (Recommended)

# Install cargo-binstall if needed
cargo install cargo-binstall

# Install tanuki-mcp (downloads pre-built binary)
cargo binstall tanuki-mcp

From crates.io

cargo install tanuki-mcp

Building from Source

git clone https://github.com/tarfu/tanuki-mcp
cd tanuki-mcp
cargo build --release
./target/release/tanuki-mcp

Configuration

Create tanuki-mcp.toml:

[gitlab]
url = "https://gitlab.com"
token = "glpat-xxxxxxxxxxxxxxxxxxxx"

[access_control]
all = "read"

[access_control.categories.issues]
level = "full"

[access_control.categories.merge_requests]
level = "full"
deny = ["merge_merge_request"]

See docs/CONFIGURATION.md for complete reference.

Access Control

tanuki-mcp provides hierarchical access control:

Global Base → Category → Action → Project-Specific

Access Levels

Example: Production-Safe Setup

[access_control]
all = "read"
deny = ["delete_.*"]

[access_control.categories.issues]
level = "full"

[access_control.projects."company/production"]
all = "read"
deny = [".*"]
allow = ["list_.*", "get_.*"]

See docs/ACCESS_CONTROL.md for detailed documentation.

Tool Categories

Transport Modes

stdio (Default)

For integration with Claude Code:

{
  "mcpServers": {
    "tanuki-mcp": {
      "command": "tanuki-mcp",
      "env": {
        "TANUKI_MCP__GITLAB_URL": "https://gitlab.com",
        "TANUKI_MCP__GITLAB_TOKEN": "glpat-xxx"
      }
    }
  }
}

HTTP (Streamable HTTP)

For web clients and programmatic access:

tanuki-mcp --http --host 0.0.0.0 --port 8080

Endpoints:

• /mcp - MCP protocol (Streamable HTTP)
• /health - Health check ({"status": "ok"})

Dashboard

Access the monitoring dashboard at http://localhost:19892:

• Configuration summary
• Project access statistics
• Tool usage metrics
• Recent request log

# Disable dashboard
tanuki-mcp --no-dashboard

# Custom port
tanuki-mcp --dashboard-port 9000

Environment Variables

TANUKI_MCP__GITLAB_URL=https://gitlab.com
TANUKI_MCP__GITLAB_TOKEN=glpat-xxx
TANUKI_MCP__SERVER_TRANSPORT=http
TANUKI_MCP__ACCESS_CONTROL_ALL=read
TANUKI_MCP__DASHBOARD_ENABLED=true

CLI Arguments

Requirements

• Rust 1.83+ (for building from source)
• GitLab Personal Access Token with appropriate scopes:
  • read_api for read operations
  • api for full functionality

Development

Dependencies

# Task runner - choose one (both Justfile and Taskfile.yml are available)
brew install just       # https://just.systems
brew install go-task    # https://taskfile.dev

# For release management (cargo set-version --bump)
cargo install cargo-edit

Available Tasks

# Using just (Justfile)
just --list        # List all tasks
just check         # Run all checks (fmt, clippy, test, doc)
just release patch # Create a release (tag + version bump)
just e2e           # Run E2E tests

# Using task (Taskfile.yml)
task --list               # List all tasks
task check                # Run all checks (fmt, clippy, test, doc)
task release VERSION=patch   # Create a release (tag + version bump)
task e2e                  # Run E2E tests

Creating a Release

# Using just
just release patch          # Bump patch version (0.1.1 -> 0.1.2)
just release minor          # Bump minor version (0.1.1 -> 0.2.0)
just release major          # Bump major version (0.1.1 -> 1.0.0)
just release 1.0.0          # Set explicit version
just release-push           # Push main + version tag

# Using task
task release VERSION=patch  # Bump patch version
task release VERSION=minor  # Bump minor version
task release VERSION=1.0.0  # Set explicit version
task release VERSION=patch SKIP_E2E=true  # Skip E2E tests
task release-push           # Push main + version tag

License

MIT