Godig

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

[](https://github.com/samber/godig/releases)

[](https://pkg.go.dev/github.com/samber/godig)

[](https://goreportcard.com/report/github.com/samber/godig) [](https://github.com/samber/godig/graphs/contributors) [](./LICENSE)

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](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](#-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

| Command | Description | | ----------------------------------------- | ------------------------------------ | | godig overview | One-call compact summary (start here)| | godig search [--symbol ] | Search packages and symbols | | godig package info | Package metadata | | godig package imports | Packages that a package imports | | godig package doc --format | Package documentation (md/text/html) | | godig package examples | Documentation with examples (--symbol to scope) | | godig package licenses | Package licenses | | godig symbol doc | One symbol's signature + doc | | godig symbol examples | One symbol's runnable examples | | godig module info | Module metadata (incl. size + min Go version) | | godig module licenses | Module licenses | | godig module readme | Module README | | godig dependencies | Module dependencies from its go.mod | | godig packages | List a module's packages | | godig versions | List module versions | | godig major-versions | List major versions (v1, v2, v3 ...) | | godig imported-by | Packages that import a package | | godig symbols | Exported symbols of a package | | godig vulns | Known vulnerabilities | | godig mcp | Run the MCP server (stdio or http) |

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

| Command | Filterable fields | | ---------------- | --------------------------------------------------------------------------------- | | search | modulePath, packagePath, synopsis, version | | versions | version, modulePath, deprecated (bool), retracted (bool), hasGoMod (bool), commitTime | | packages | path, name, synopsis, isRedistributable (bool) | | imported-by | path (the importing package path) | | symbols | name, kind (Function/Method/Type/Variable/Constant), synopsis, parent | | major-versions | modulePath, major, version, isLatest (bool) |

> [!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!

[](https://github.com/sponsors/samber)

📝 License

Copyright © 2026 Samuel Berthe.

This project is [MIT](./LICENSE) licensed.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: samber
• Source: samber/godig
• License: MIT
• Homepage: https://godig.samber.dev/mcp

Install and usage instructions live in the source repository linked above.