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.

[!TIP] Looking for a Go library instead of a CLI? Use samber/go-pkggodev-client — the typed pkg.go.dev client that powers godig.

🚀 Install

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.

💡 Quick start

# 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).

🧠 Commands

Run godig --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 (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.

🔎 Filters

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):

[!NOTE] Identifiers follow the pkg.go.dev API’s filter schema, using the lowercase JSON field name. kind values are capitalized (Function, not func). An unknown identifier is rejected by the API with HTTP 400 undefined identifier: , which names the offending field.

📫 MCP server

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" } } }

🥷 Skill

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

🔧 How it works

• 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.

🤝 Contributing

# Install dev dependencies
make tools

# Run tests
make test

# Lint
make lint

# Build (with version ldflags)
make build

👤 Contributors

🙏 Acknowledgements

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

💫 Show your support

Give a ⭐️ if this project helped you!

📝 License

Copyright © 2026 Samuel Berthe.

This project is MIT licensed.