godig - CLI & MCP server for pkg.go.dev

godig is a CLI and an MCP server for exploring Go packages and modules via the pkg.go.dev API: search, documentation, symbols, versions, importers and vulnerabilities — from your shell or from an AI agent.

Its commands and MCP tools are built from a small hand-written catalog (internal/spec) and call the typed go-pkggodev-client. All operations are read-only and need no authentication.

go install github.com/samber/godig/cmd/godig@latest

# AI Agent Skill:
npx skills add https://github.com/samber/cc-skills-golang --skill golang-pkg-go-dev

# Register the MCP server into Claude Code (stdio)
claude mcp add pkg-go-dev -- godig mcp

Requires Go >= 1.25. See Skill to also register the MCP server with your agent.

# Overview — one compact call: metadata, latest + recent versions, licenses, vulns
godig overview github.com/samber/ro

# Search
godig search "result option monad" --limit 5

# Package facets
godig package info github.com/samber/ro
godig package imports github.com/samber/ro
godig package doc github.com/samber/ro --format md
godig package examples github.com/samber/ro
godig package examples github.com/samber/ro --symbol Map   # examples for one symbol only
godig package licenses github.com/samber/ro

# Single symbol (token-efficient vs the full package doc/examples)
godig symbol doc github.com/samber/ro Map
godig symbol examples github.com/samber/mo Either.ForEach

# Module facets
godig module info github.com/samber/ro            # incl. download size + min Go version
godig module readme github.com/samber/ro
godig module licenses github.com/samber/ro
godig dependencies github.com/samber/oops         # go.mod requires/replaces/excludes

# Lists (auto-paginated; --limit to cap, -o md for a Markdown table)
godig versions github.com/samber/ro -o md
godig major-versions github.com/samber/do        # v1, v2, v3 ... (separate modules)
godig major-versions github.com/samber/do --exclude-pseudo   # drop majors whose latest is a pseudo-version
godig packages github.com/samber/ro
godig imported-by github.com/samber/ro --limit 20
godig symbols github.com/samber/ro

# Filter (a Go boolean expression over item fields) and build context (goos/goarch)
godig versions github.com/samber/ro --filter 'hasPrefix(version, "v0.3")'
godig symbols github.com/samber/ro --goos linux --goarch amd64

# Vulnerabilities
godig vulns github.com/samber/ro

# Run as an MCP server (stdio; --transport http for HTTP)
godig mcp

Global flags: -o, --output (table default, json, raw, md), --base-url, --vuln-base-url (Go vulnerability database, default https://vuln.go.dev), --timeout, --log-level (debug|info|warn|error|off, default error; logs go to stderr). All flags can also be set via GODIG_-prefixed environment variables.

Exit codes: 0 success, 1 runtime error (e.g. network, package not found), 2 usage error (missing/invalid arguments or flags, or a group invoked without a subcommand).

Run godig <command> --help (or godig package --help) for per-command flags. Each operation is also exposed as an MCP tool (e.g. overview, package-info, module-readme). Utility commands: godig version and godig completion <shell> (bash/zsh/fish/powershell).

For AI agents (token-efficient): start with overview — one call returns a compact summary (no large docs). Fetch doc, examples, module readme or licenses only when the full text is actually needed, and cap long lists (versions, imported-by) with --limit.

The --filter flag (on search, versions, packages, imported-by, symbols, major-versions) takes a Go boolean expression evaluated server-side over each item. The identifiers are the item's fields — which differ per command, so a field valid for one list is not valid for another (e.g. search exposes packagePath, not path). Helper functions include hasPrefix, hasSuffix and contains.

godig search "result option" --filter 'hasPrefix(packagePath, "github.com/samber/")'
godig versions github.com/samber/ro --filter 'hasPrefix(version, "v0.3")'
godig symbols github.com/samber/ro  --filter 'kind == "Function"'
godig imported-by github.com/samber/ro --filter 'contains(path, "/internal/")'

Available fields per command (string unless noted):

godig mcp runs an MCP server exposing one read-only tool per operation, over either transport.

stdio (default) — the client launches the binary on demand:

claude mcp add pkg-go-dev -- godig mcp

{ "mcpServers": { "pkg-go-dev": { "command": "godig", "args": ["mcp"] } } }

streamable HTTP — a shared, long-running server at /mcp (--addr, default :8080):

godig mcp --transport http --addr :8080
claude mcp add --transport http pkg-go-dev http://localhost:8080/mcp

{ "mcpServers": { "pkg-go-dev": { "type": "http", "url": "http://localhost:8080/mcp" } } }

A public instance is hosted on Clever Cloud at https://godig.samber.dev/mcp — register it without running anything locally:

claude mcp add --transport http pkg-go-dev https://godig.samber.dev/mcp

{ "mcpServers": { "pkg-go-dev": { "type": "http", "url": "https://godig.samber.dev/mcp" } } }

A companion AI-agent skill, golang-pkg-go-dev, lives in samber/cc-skills-golang. It covers both setup (registering the MCP server) and usage workflows (intent → command/tool), and triggers when exploring Go packages: docs, versions, importers, vulnerabilities.

npx skills add https://github.com/samber/cc-skills-golang --skill golang-pkg-go-dev

• internal/spec is a hand-written catalog of the operations (name, flags, types).
• The CLI (cmd/godig) and the MCP server (internal/mcpserver) both build their surface by looping over that catalog — one Cobra command and one MCP tool per operation.
• internal/dispatch is the shared core: it maps each operation name to the matching typed go-pkggodev-client call; results render as table, json or raw.

# Install dev dependencies
make tools

# Run tests
make test

# Lint
make lint

# Build (with version ldflags)
make build

Thanks to Clever Cloud for hosting the public godig.samber.dev MCP server.

Give a ⭐️ if this project helped you!

Copyright © 2026 Samuel Berthe.

This project is MIT licensed.