MCP Navigator (Go)

A comprehensive Model Context Protocol (MCP) client implementation in Go, providing both a powerful CLI and a library for integration into other applications.

Features

🔍 Server Discovery: Automatically discover MCP servers on TCP ports, HTTP endpoints, and Docker containers
🔌 Multiple Transports: Support for TCP, HTTP/SSE, HTTP Streaming, STDIO, WebSocket, and Docker-based connections
💬 Interactive CLI: Full-featured command-line interface for server interaction
🛠️ Complete MCP Protocol: Full MCP 2025-11-25 specification compliance with Tools, Resources, and Prompts
🐳 Docker Support: Direct support for Docker-based MCP servers
🌐 HTTP Support: Support for both Server-Sent Events (SSE) and streaming HTTP modes
🔧 Configurable Logging: Optional debug mode with component-based logging for troubleshooting
📚 Library Integration: Use as a library in your Go applications (Library Documentation)
⚡ High Performance: Written in Go for speed and efficiency
✅ Production Ready: Full test coverage across all supported protocols

Installation

From Source

git clone https://github.com/kunalkushwaha/mcp-navigator-go.git
cd mcp-navigator-go
go mod download
go build -o mcp-navigator main.go

Using Go Install

go install github.com/kunalkushwaha/mcp-navigator-go@latest

As a Library

go get github.com/kunalkushwaha/mcp-navigator-go

Quick Start

1. Discover Available MCP Servers

./mcp-navigator discover

This will show available servers including:

TCP servers on common MCP ports (8811, 8812, 8813, etc.)
HTTP MCP servers (both SSE and streaming modes)
Docker-based MCP servers
Standard Docker MCP configuration (alpine/socat)

2. Interactive Mode

./mcp-navigator interactive

This starts the interactive CLI where you can:

help - Show available commands
discover - Find MCP servers
connect <server-name-or-index> - Connect to a server
list-tools - List available tools on connected server
list-resources - List available resources on connected server
call-tool <tool-name> [json-args] - Execute a tool
status - Show connection status
exit - Exit the client

3. Direct Commands

Connect to a TCP server:

./mcp-navigator connect --tcp --host localhost --port 8811

Connect to HTTP MCP server (SSE mode):

./mcp-navigator connect --http --url http://localhost:8812 --endpoint /sse/

Connect to HTTP MCP server (streaming mode):

./mcp-navigator connect --http --url http://localhost:8813 --endpoint /mcp

Connect to Docker MCP server:

./mcp-navigator connect --docker

Execute a tool directly:

./mcp-navigator tool --name search --arguments '{"query": "golang"}' --docker

Library Usage

MCP Navigator can be used as a library in your Go applications.

📚 Documentation:

Library Documentation - Comprehensive guide with examples and best practices
API Reference - Concise API documentation and usage patterns

Quick Library Example

package main

import (
    "context"
    "log"
    "time"

    "github.com/kunalkushwaha/mcp-navigator-go/pkg/client"
    "github.com/kunalkushwaha/mcp-navigator-go/pkg/transport"
)

func main() {
    // Create client with TCP transport
    mcpClient := client.NewMCPClient(transport.NewTCPTransport("localhost", 8811))
    
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    
    // Connect and initialize
    err := mcpClient.Connect(ctx)
    if err != nil {
        log.Fatalf("Failed to connect: %v", err)
    }
    defer mcpClient.Close()
    
    serverInfo, err := mcpClient.Initialize(ctx, "my-app", "1.0.0")
    if err != nil {
        log.Fatalf("Failed to initialize: %v", err)
    }
    
    log.Printf("Connected to: %s %s", serverInfo.Name, serverInfo.Version)
    
    // List and execute tools
    tools, err := mcpClient.ListTools(ctx)
    if err != nil {
        log.Fatalf("Failed to list tools: %v", err)
    }
    
    for _, tool := range tools {
        log.Printf("Available tool: %s", tool.Name)
    }
}

📖 See LIBRARY.md for:

Complete transport examples (TCP, HTTP SSE, HTTP Streaming, STDIO, WebSocket)
Server discovery integration
Advanced usage patterns (builder pattern, service wrappers, error handling)
Testing strategies and mock implementations
Performance optimization techniques

📋 See API.md for:

Complete API reference with all methods and types
Quick usage patterns and code snippets
Error handling strategies
Configuration options

Debug Logging and Troubleshooting

MCP Navigator supports configurable debug logging to help troubleshoot issues. Debug mode is disabled by default for clean production output.

Enabling Debug Logging

// In library code, enable debug mode
config := client.ClientConfig{
    Name:    "my-app",
    Version: "1.0.0",
    Debug:   true,  // Enable debug logging
}

client := client.NewClient(transport, config)

Debug Output Example

With Debug: true, you'll see detailed component-based logs:

[CLIENT] Connecting to MCP server...
[CLIENT] Connected to MCP server
[INIT] Initializing MCP protocol with client: my-app 1.0.0
[INIT] Received initialize response from server: my-server v1.0
[CLIENT] Listing available tools...
[PARSE] Parsed response - Tools count=4
[TRANSPORT] Bytes received: 256

Component Prefixes

Debug logs include component prefixes to identify the source:

[CLIENT] - High-level client operations
[INIT] - Protocol initialization details
[TRANSPORT] - Low-level transport operations
[PARSE] - JSON parsing and unmarshaling

For detailed debugging guidance, see Debug Logging Guide.

Protocol Support

MCP Navigator supports multiple transport protocols with consistent API:

Protocol	Use Case	Status
TCP	Local servers, fast communication	✅ Fully Supported
STDIO	Process/tool integration	✅ Fully Supported
WebSocket	Remote servers, web compatibility	✅ Fully Supported
HTTP/SSE	Server-Sent Events	✅ Fully Supported
HTTP Streaming	Long-polling streams	✅ Fully Supported
Docker	Container-based servers	✅ Fully Supported

For protocol testing examples, see Protocol Testing Guide.

CLI Usage

The following examples show CLI usage. For library integration, see Library Documentation.

Server Discovery

# Discover all servers
./mcp-navigator discover

# Scan specific host
./mcp-navigator discover --host 192.168.1.100

# Only scan TCP ports
./mcp-navigator discover --tcp-only

# Only check Docker containers
./mcp-navigator discover --docker-only

# Custom port range
./mcp-navigator discover --start-port 8000 --end-port 9000

Connecting to Servers

# TCP connection
./mcp-navigator connect --tcp --host localhost --port 8811

# HTTP connection (SSE mode)
./mcp-navigator connect --http --url http://localhost:8812 --endpoint /sse/

# HTTP connection (streaming mode) 
./mcp-navigator connect --http --url http://localhost:8813 --endpoint /mcp

# STDIO connection
./mcp-navigator connect --stdio --command "node" --args "server.js"

# Docker connection (uses alpine/socat bridge)
./mcp-navigator connect --docker

# With custom timeout
./mcp-navigator connect --tcp --host localhost --port 8811 --timeout 45s

Tool Execution

# Execute tool with JSON arguments
./mcp-navigator tool --name search --arguments '{"query": "golang", "limit": 10}' --tcp

# Execute tool via Docker MCP server
./mcp-navigator tool --name docker --arguments '{"command": "ps -a"}' --docker

# Execute tool with no arguments
./mcp-navigator tool --name list-files --docker

Docker MCP Server Support

The client automatically supports the standard Docker-based MCP server configuration used by Claude Desktop:

{
  "mcpServers": {
    "MCP_DOCKER": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "alpine/socat",
        "STDIO",
        "TCP:host.docker.internal:8811"
      ]
    }
  }
}

This configuration allows MCP servers running in Docker containers to communicate with external TCP services.

Interactive Mode Example

$ ./mcp-navigator interactive

🚀 MCP Navigator Interactive Mode
Type 'help' for available commands.
🔍 Discovering MCP servers...
✅ Found 6 server(s):
  1. TCP Server localhost:8811 (tcp)
     Address: localhost:8811
  2. TCP Server localhost:8812 (tcp)
     Address: localhost:8812
  3. TCP Server localhost:8813 (tcp)
     Address: localhost:8813
  4. HTTP MCP Server (SSE) localhost:8812/sse/ (http)
     Address: localhost:8812
  5. HTTP MCP Server (Streaming) localhost:8813/mcp (http)
     Address: localhost:8813
  6. Docker MCP (Direct TCP) (docker)
     Address: localhost:8811

mcp-client> help

📋 Available Commands:
  help              - Show this help message
  discover          - Discover available MCP servers
  connect <n>       - Connect to a server by name or index
  disconnect        - Disconnect from current server
  list-tools        - List tools available on current server
  list-resources    - List resources available on current server
  call-tool <n> [args] - Call a tool with optional JSON arguments
  status            - Show connection status
  exit/quit         - Exit the client

mcp-client> connect 5
🔌 Connecting to HTTP MCP Server (Streaming) localhost:8813/mcp...
✅ Connected to HTTP MCP Server (Streaming) localhost:8813/mcp
🚀 Server: Docker AI MCP Gateway 2.0.1

mcp-client> list-tools
📝 Available tools (4):
  1. docker
     Description: use the docker cli
  2. fetch
     Description: Fetches a URL from the internet and optionally extracts its contents as markdown
  3. fetch_content
     Description: Fetch and parse content from a webpage URL
  4. search
     Description: Search DuckDuckGo and return formatted results

mcp-client> call-tool search {"query": "Model Context Protocol"}
🔧 Calling tool: search
📤 Tool result:
The Model Context Protocol (MCP) is an open standard that enables secure connections between AI assistants and data sources...

mcp-client> status

📊 Status:
  Available servers: 6
  Current connection: HTTP MCP Server (Streaming) localhost:8813/mcp ✅
  Server info: Docker AI MCP Gateway 2.0.1

mcp-client> exit

👋 Shutting down MCP client...
✅ Goodbye!

Configuration

Environment Variables

MCP_CLIENT_TIMEOUT: Default timeout for operations (default: 30s)
MCP_CLIENT_HOST: Default host for TCP connections (default: localhost)
MCP_CLIENT_PORT: Default port for TCP connections (default: 8811)
MCP_CLIENT_URL: Default URL for HTTP connections (default: http://localhost:8812)
MCP_CLIENT_ENDPOINT: Default endpoint for HTTP connections (default: /mcp)
MCP_CLIENT_VERBOSE: Enable verbose logging (default: false)

Config File

Create ~/.mcp-client.yaml:

# Default connection settings
host: localhost
port: 8811
timeout: 30s

# Discovery settings
discovery:
  startPort: 8810
  endPort: 8820
  timeout: 5s

# Logging
verbose: false

Command Reference

Global Flags

--config: Config file path
--verbose, -v: Enable verbose output

Commands

`discover`

Discover available MCP servers

Flags:

--host: Host to scan (default: localhost)
--start-port: Start port for scanning (default: 8810)
--end-port: End port for scanning (default: 8820)
--timeout: Discovery timeout (default: 5s)
--tcp-only: Only scan TCP ports
--docker-only: Only check Docker containers

`connect`

Connect to an MCP server and show available tools/resources

Flags:

--type: Connection type (tcp, stdio, docker)
--tcp, -t: Use TCP transport
--stdio, -s: Use STDIO transport
--docker, -d: Use Docker transport
--host: TCP host (default: localhost)
--port: TCP port (default: 8811)
--command: Command for STDIO transport
--args: Arguments for STDIO command
--timeout: Connection timeout (default: 30s)

`tool`

Execute a specific tool on an MCP server

Flags:

--name: Tool name (required)
--arguments: JSON arguments for the tool (default: "{}")
All connection flags from connect command

`interactive`

Start interactive mode

Aliases: i, shell

Development

Project Structure

├── main.go                 # Entry point
├── internal/
│   └── cli/               # CLI commands
│       ├── root.go        # Root command and configuration
│       ├── discover.go    # Server discovery command
│       ├── connect.go     # Connection command
│       ├── tool.go        # Tool execution command
│       └── interactive.go # Interactive mode
├── pkg/
│   ├── client/           # MCP client implementation
│   ├── discovery/        # Server discovery logic
│   ├── mcp/             # MCP protocol types and utilities
│   └── transport/       # Transport implementations (TCP, STDIO, WebSocket, HTTP)
├── go.mod
└── README.md

Building

go build -o mcp-client main.go

Testing

go test ./...

Running in Development

go run main.go interactive

Requirements

Go 1.21 or later
Docker (for Docker-based MCP servers)
MCP Server running on TCP port or Docker

License

MIT License - see LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github		.github
examples		examples
internal/cli		internal/cli
pkg		pkg
tests		tests
.gitignore		.gitignore
API.md		API.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LIBRARY.md		LIBRARY.md
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum
main.go		main.go

License

AgenticGoKit/mcp-navigator-go

Folders and files

Latest commit

History

Repository files navigation

MCP Navigator (Go)

Features

Installation

From Source

Using Go Install

As a Library

Quick Start

1. Discover Available MCP Servers

2. Interactive Mode

3. Direct Commands

Library Usage

Quick Library Example

Debug Logging and Troubleshooting

Enabling Debug Logging

Debug Output Example

Component Prefixes

Protocol Support

CLI Usage

Server Discovery

Connecting to Servers

Tool Execution

Docker MCP Server Support

Interactive Mode Example

Configuration

Environment Variables

Config File

Command Reference

Global Flags

Commands

discover

connect

tool

interactive

Development

Project Structure

Building

Testing

Running in Development

Requirements

Related

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Languages

`discover`

`connect`

`tool`

`interactive`

Packages