Repository: micro/go-micro

Stars: 22729

CLAUDE.md Copy Chapter

CLAUDE.md - Go Micro Project Guide

Project Overview Copy Chapter

Go Micro is a framework for distributed systems development in Go. It provides pluggable abstractions for service discovery, RPC, pub/sub, config, auth, storage, and more.

The framework is evolving into an AI-native platform where every microservice is automatically accessible to AI agents via the Model Context Protocol (MCP).

Build & Test Copy Chapter

Run all tests

make test
Run tests for a specific package

go test ./gateway/mcp/...
go test ./ai/...
go test ./model/...
Lint

make lint
Format

make fmt
Build CLI

go build -o micro ./cmd/micro
Run locally with hot reload

micro run

Project Structure Copy Chapter

go-micro/
├── ai/             # AI model providers (Anthropic, OpenAI)
├── auth/           # Authentication (JWT, no-op)
├── broker/         # Message broker (NATS, RabbitMQ)
├── cache/          # Caching (Redis)
├── client/         # RPC client (gRPC)
├── cmd/micro/      # CLI tool (run, deploy, mcp, build, server)
├── codec/          # Message codecs (JSON, Proto)
├── config/         # Dynamic config (env, file, etcd, NATS)
├── errors/         # Error handling
├── events/         # Event system (NATS JetStream)
├── gateway/
│   ├── api/        # REST API gateway
│   └── mcp/        # MCP gateway (core AI integration)
│       └── deploy/ # Helm charts for MCP gateway
├── health/         # Health checking
├── logger/         # Logging
├── metadata/       # Context metadata
├── model/          # Typed data models (CRUD, queries, schemas)
├── registry/       # Service discovery (mDNS, Consul, etcd)
├── selector/       # Client-side load balancing
├── server/         # RPC server
├── service/        # Service interface + profiles
├── store/          # Data persistence (Postgres, NATS KV)
├── transport/      # Network transport
├── wrapper/        # Middleware (auth, trace, metrics)
├── examples/       # Working examples
└── internal/       # Non-public: docs, utils, test harness

Key Architectural Decisions Copy Chapter

- Plugin architecture: All abstractions use Go interfaces. Defaults work out of the box, everything is swappable.
- Progressive complexity: Zero-config for development, full control for production.
- AI-native by default: Every service is automatically an MCP tool. No extra code needed.
- In-repo plugins: Plugins live in the main repo to avoid version compatibility issues.
- Reflection-based registration: Handlers are registered via reflection for minimal boilerplate.

Code Conventions Copy Chapter

- Standard Go conventions (gofmt, golint)
- Functional options pattern for configuration (WithX() functions)
- Interface-first design: define the interface, then implement
- Tests alongside code (not in separate test directories)
- Commit messages: imperative mood, concise summary line

Current Focus & Priorities (March 2026) Copy Chapter

Status Copy Section

Priority 1: Agent Showcase & Examples Copy Section

Priority 2: Additional Protocol Support Copy Section

Priority 3: Kubernetes & Deployment Copy Section

Recently Completed Copy Section

Key Files Copy Chapter

| Purpose | File |
|---------|------|
| MCP Gateway | gateway/mcp/mcp.go |
| MCP Docs | gateway/mcp/DOCUMENTATION.md |
| AI Interface | ai/model.go |
| Model Layer | model/model.go |
| CLI Entry | cmd/micro/main.go |
| MCP CLI | cmd/micro/mcp/ |
| Server (run/server) | cmd/micro/server/server.go |
| Roadmap | internal/docs/ROADMAP_2026.md |
| Status | internal/docs/CURRENT_STATUS_SUMMARY.md |
| Changelog | CHANGELOG.md |
| Docs Site | internal/website/docs/ |

Roadmap & Status Documents Copy Chapter

- ROADMAP.md - General framework roadmap
- internal/docs/ROADMAP_2026.md - AI-native era roadmap with business model
- internal/docs/CURRENT_STATUS_SUMMARY.md - Quick status overview
- internal/docs/PROJECT_STATUS_2026.md - Detailed technical status
- internal/docs/IMPLEMENTATION_SUMMARY.md - Implementation notes
- CHANGELOG.md - What changed and when

Contributing Copy Chapter

See CONTRIBUTING.md for full guidelines. Key points:
- Open an issue before large changes
- Include tests for new features
- Run make test and make lint before submitting
- Follow commit message format: type: description (e.g., feat: add WebSocket transport)

README.md Copy Chapter

Go Micro  

Go Micro is a framework for distributed systems development.

📖 Documentation | Sponsored by Anthropic

*️⃣ Try Mu.xyz - a new app platform by the creator of Go Micro

Overview Copy Chapter

Go Micro provides the core requirements for distributed systems development including RPC and Event driven communication.
The Go Micro philosophy is sane defaults with a pluggable architecture. We provide defaults to get you started quickly
but everything can be easily swapped out.

Features Copy Chapter

Go Micro abstracts away the details of distributed systems. Here are the main features.

- Authentication - Auth is built in as a first class citizen. Authentication and authorization enable secure
zero trust networking by providing every service an identity and certificates. This additionally includes rule
based access control.

- Dynamic Config - Load and hot reload dynamic config from anywhere. The config interface provides a way to load application
level config from any source such as env vars, file, etcd. You can merge the sources and even define fallbacks.

- Data Storage - A simple data store interface to read, write and delete records. It includes support for many storage backends
in the plugins repo. State and persistence becomes a core requirement beyond prototyping and Micro looks to build that into the framework.

- Data Model - A typed data model layer with CRUD operations, queries, and multiple backends (memory, SQLite, Postgres). Define Go
structs with tags and get type-safe Create/Read/Update/Delete/List/Count operations. Accessible via service.Model() alongside
service.Client() and service.Server() for a complete service experience: call services, handle requests, save and query data.

- Service Discovery - Automatic service registration and name resolution. Service discovery is at the core of micro service
development. When service A needs to speak to service B it needs the location of that service. The default discovery mechanism is
multicast DNS (mdns), a zeroconf system.

- Load Balancing - Client side load balancing built on service discovery. Once we have the addresses of any number of instances
of a service we now need a way to decide which node to route to. We use random hashed load balancing to provide even distribution
across the services and retry a different node if there's a problem.

- Message Encoding - Dynamic message encoding based on content-type. The client and server will use codecs along with content-type
to seamlessly encode and decode Go types for you. Any variety of messages could be encoded and sent from different clients. The client
and server handle this by default. This includes protobuf and json by default.

- RPC Client/Server - RPC based request/response with support for bidirectional streaming. We provide an abstraction for synchronous
communication. A request made to a service will be automatically resolved, load balanced, dialled and streamed.

- Async Messaging - PubSub is built in as a first class citizen for asynchronous communication and event driven architectures.
Event notifications are a core pattern in micro service development. The default messaging system is a HTTP event message broker.

- MCP Integration - An MCP gateway you can integrate as a library, server or CLI command which automatically exposes services
as tools for agents or other AI applications. Every service/endpoint get's converted into a callable tool.

- Multi-Service Binaries - Run multiple services in a single process with isolated state per service. Start as a modular monolith,
split into separate deployments when you need independent scaling. Each service gets its own server, client, and store while sharing
the registry and broker for inter-service communication.

- Pluggable Interfaces - Go Micro makes use of Go interfaces for each distributed system abstraction. Because of this these interfaces
are pluggable and allows Go Micro to be runtime agnostic. You can plugin any underlying technology.

Getting Started Copy Chapter

To make use of Go Micro

go get go-micro.dev/[email protected]

Create a service and register a handler

package main
import (
        "go-micro.dev/v5"
)
type Request struct {
        Name string json:"name"
}
type Response struct {
        Message string json:"message"
}
type Say struct{}
func (h Say) Hello(ctx context.Context, req Request, rsp *Response) error {
        rsp.Message = "Hello " + req.Name
        return nil
}
func main() {
        // create the service
        service := micro.New("helloworld")
        // register handler
        service.Handle(new(Say))
        // run the service
        service.Run()
}

Set a fixed address

service := micro.New("helloworld", micro.Address(":8080"))

Call it via curl

curl -XPOST \
     -H 'Content-Type: application/json' \
     -H 'Micro-Endpoint: Say.Hello' \
     -d '{"name": "alice"}' \
      http://localhost:8080

MCP & AI Agents Copy Chapter

Go Micro is designed for an agent-first workflow. Every service you build automatically becomes a tool that AI agents can discover and use via the Model Context Protocol (MCP).

- 🤖 Agent Playground — Chat with your services through an interactive AI agent at /agent
- 🔧 MCP Tools Registry — Browse all services exposed as AI-callable tools at /api/mcp/tools
- 📖 MCP Documentation — Full guide to MCP integration, auth, and scopes

Services as Tools Copy Section

Write a normal Go Micro service and it's instantly available as an MCP tool:

// SayHello greets a person by name.
// @example {"name": "Alice"}
func (g GreeterService) SayHello(ctx context.Context, req HelloRequest, rsp *HelloResponse) error {
    rsp.Message = "Hello " + req.Name
    return nil
}

Run with micro run and the agent playground and MCP tools registry are ready:

micro run
Agent Playground:  http://localhost:8080/agent

MCP Tools:         http://localhost:8080/api/mcp/tools

Use micro mcp serve for local AI tools like Claude Code, or connect any MCP-compatible agent to the HTTP endpoint.

See the MCP guide for authentication, scopes, and advanced usage.

Multi-Service Binaries Copy Chapter

Run multiple services in a single binary — start as a modular monolith, split into separate deployments later when you actually need to.

users := micro.New("users", micro.Address(":9001"))
orders := micro.New("orders", micro.Address(":9002"))
users.Handle(new(Users))
orders.Handle(new(Orders))
// Run all services together with shared lifecycle
g := micro.NewGroup(users, orders)
g.Run()

Each service gets its own server, client, store, and cache while sharing the registry, broker, and transport — so they can discover and call each other within the same process.

See the multi-service example for a working demo.

Data Model Copy Chapter

Go Micro includes a typed data model layer for persistence. Define a struct, tag a key field, and get type-safe CRUD and query operations backed by memory, SQLite, or Postgres.

import (
        "go-micro.dev/v5/model"
        "go-micro.dev/v5/model/sqlite"
)
// Define your data type
type User struct {
        ID    string json:"id" model:"key"
        Name  string json:"name"
        Email string json:"email" model:"index"
        Age   int    json:"age"
}

Register your types and use the model:

service := micro.New("users")
// Register and use the service's model backend
db := service.Model()
db.Register(&User{})
// CRUD operations
db.Create(ctx, &User{ID: "1", Name: "Alice", Email: "[email protected]", Age: 30})
user := &User{}
db.Read(ctx, "1", user)
user.Name = "Alice Smith"
db.Update(ctx, user)
db.Delete(ctx, "1", &User{})

Query with filters, ordering, and pagination:

var results []*User
// Find users by field
db.List(ctx, &results, model.Where("email", "[email protected]"))
// Complex queries
db.List(ctx, &results,
        model.WhereOp("age", ">=", 18),
        model.OrderDesc("name"),
        model.Limit(10),
        model.Offset(20),
)
count, _ := users.Count(ctx, model.Where("age", 30))

Swap backends with an option:

// Development: in-memory (default)
service := micro.New("users")
// Production: SQLite or Postgres
db, _ := sqlite.New(model.WithDSN("file:app.db"))
service := micro.New("users", micro.Model(db))

Every service gets Client(), Server(), and Model() — call services, handle requests, and save data all from the same interface.

Examples Copy Chapter

Check out /examples for runnable code:
- hello-world - Basic RPC service
- web-service - HTTP REST API
- multi-service - Multiple services in one binary
- mcp - MCP integration with AI agents

See all examples for more.

Protobuf Copy Chapter

Install the code generator and see usage in the docs:

go install go-micro.dev/v5/cmd/[email protected]

Note: Use a specific version instead of @latest to avoid module path conflicts. See releases for the latest version.

Docs: internal/website/docs/getting-started.md

Command Line Copy Chapter

Install the CLI:

go install go-micro.dev/v5/cmd/[email protected]

Note: Use a specific version instead of @latest to avoid module path conflicts. See releases for the latest version.

Quick Start Copy Section

micro new helloworld   # Create a new service
cd helloworld
micro run              # Run with API gateway and hot reload

Then open http://localhost:8080 to see your service and call it from the browser.

Development Workflow Copy Section

| Stage | Command | Purpose |
|-------|---------|---------|
| Develop | micro run | Local dev with hot reload and API gateway |
| Build | micro build | Compile production binaries |
| Deploy | micro deploy | Push to a remote Linux server via SSH + systemd |
| Dashboard | micro server | Optional production web UI with JWT auth |

micro run Copy Section

micro run starts your services with:
- Web Dashboard - Browse and call services at /
- Agent Playground - AI chat with MCP tools at /agent
- API Explorer - Browse endpoints and schemas at /api
- API Gateway - HTTP to RPC proxy at /api/{service}/{method} (no auth in dev mode)
- MCP Tools - Services as AI tools at /api/mcp/tools
- Health Checks - Aggregated health at /health
- Hot Reload - Auto-rebuild on file changes

Note: micro run and micro server use a unified gateway architecture. See Gateway Architecture for details.

micro run                    # Gateway on :8080
micro run --address :3000    # Custom gateway port
micro run --no-gateway       # Services only
micro run --env production   # Use production environment

Configuration Copy Section

For multi-service projects, create a micro.mu file:

service users
    path ./users
    port 8081
service posts
    path ./posts
    port 8082
    depends users
env development
    DATABASE_URL sqlite://./dev.db

The gateway runs on :8080 by default, so services should use other ports.

Deployment Copy Section

Deploy to any Linux server with systemd:

On your server (one-time setup)

curl -fsSL https://go-micro.dev/install.sh | sh
sudo micro init --server
From your laptop

micro deploy user@your-server

The deploy command:
1. Builds binaries for Linux
2. Copies via SSH to the server
3. Sets up systemd services
4. Verifies services are healthy

Optionally run micro server on the deployed machine for a production web dashboard with JWT auth, user management, and API explorer.

Manage deployed services:

micro status --remote user@server    # Check status
micro logs --remote user@server      # View logs
micro logs myservice --remote user@server -f  # Follow specific service

No Docker required. No Kubernetes. Just systemd.

See internal/website/docs/deployment.md for full deployment guide.

See cmd/micro/README.md for full CLI documentation.

Docs: internal/website/docs

Package reference: https://pkg.go.dev/go-micro.dev/v5

User Guides:
- Getting Started
- Data Model
- MCP & AI Agents
- Plugins Overview
- Learn by Example
- Deployment Guide

Architecture & Performance:
- Performance Considerations
- Reflection Usage & Philosophy

Security:
- TLS Security Migration
- Security Migration Guide

Adopters Copy Chapter

- Sourse - Work in the field of earth observation, including embedded Kubernetes running onboard aircraft, and we’ve built a mission management SaaS platform using Go Micro.