mcp2cli

Convert MCP servers to CLI tools

Usage · Architecture · Development · Guidelines · Testing · PR Workflow · Porting Parity

---

This is a Crystal port of github.com/thellimist/clihub.

Turn any MCP server into a compiled CLI binary. One command. Designed for agents.

mcp2cli generate --url https://api.githubcopilot.com/mcp/
# → ./out/api (Crystal binary with all MCP tools)

Every tool the server exposes becomes a subcommand with flags derived from its JSON Schema. Auth is handled automatically — bearer tokens, API keys, and more.

Install

# Clone and build
git clone https://github.com/dsisnero/mcp2cli.git
cd mcp2cli
shards install
shards build

# Install to your PATH
install -m 755 bin/mcp2cli ~/.local/bin/mcp2cli

If ~/.local/bin is not in your PATH, add it in your shell config (for example ~/.zshrc):

export PATH="$HOME/.local/bin:$PATH"

Requires Crystal 1.14+.

Quick Start

HTTP MCP server

mcp2cli generate --url https://api.githubcopilot.com/mcp/
./out/api list-tools

Authentication

Generated CLIs handle auth at runtime. For HTTP servers, the auth subcommand manages credentials:

# Manual bearer token
./out/api auth --token $TOKEN

# Check status
./out/api auth status

# Logout
./out/api auth logout

Auth is resolved in this order:

1. --auth-token flag
2. MCP2CLI_AUTH_TOKEN environment variable
3. ~/.config/mcp2cli/credentials.json (persisted from previous auth)
4. ~/.mcp2cli/credentials.json (fallback)
5. Unauthenticated

Pass tool input as JSON

Generated CLIs include a --from-json flag on each tool command. This lets you pass the full tool input object directly.

./out/api search-code --from-json '{"query":"function definition","language":"python"}'

Rules:

• --from-json bypasses typed tool flags.
• --from-json cannot be combined with typed flags in the same call.

How It Works

1. Connect to the MCP server (HTTP or stdio)
2. Discover all tools via tools/list
3. Generate a Crystal CLI with one subcommand per tool
4. Compile to a binary for your target platform

The generated binary is standalone — no runtime dependencies, no config files, no mcp2cli needed.

Features

• Convert MCP servers to CLI tools
• Single binary output
• Agent-friendly interface
• XDG-compliant credential storage (~/.config/mcp2cli/credentials.json)
• Support for HTTP MCP servers
• Generated CLIs actually call MCP tools (not just placeholders)
• Compatible with GitHub Copilot's MCP server (handles initialized notification gracefully)

Development

# Install dependencies
shards install

# Run tests
crystal spec

# Format code
crystal tool format src spec

# Run linter
ameba src spec

# Build project
shards build

# Run in development
bin/mcp2cli

See Development Guide for full setup instructions.

Documentation

Contributing

1. Create an issue: /forge-create-issue
2. Implement: /forge-implement-issue <number>
3. Self-review: /forge-reflect-pr
4. Address feedback: /forge-address-pr-feedback
5. Update changelog: /forge-update-changelog

Commits

Format: <type>(<scope>): <description>

Types: feat, fix, docs, refactor, test, chore, perf

Examples:

• feat(cli): add basic MCP server connection
• fix(parser): handle missing required arguments
• docs(readme): update installation instructions

Crystal Code Gates

crystal tool format --check src spec
ameba src spec
crystal spec

Porting Conventions

This is a Crystal port of github.com/thellimist/clihub.

Source of Truth

• Go code in vendor/mcp2cli/ is the authoritative source
• Preserve behavior exactly from upstream
• Use Crystal idioms without changing semantics

Porting Workflow

1. Use go-to-crystal-parity to generate inventory
2. Use porting-to-crystal for code translation
3. Verify against Go tests and behavior
4. Run Crystal quality gates before committing

Dependency Strategy

• Map Go dependencies to Crystal shards where possible
• Preserve API contracts and behavior
• Document any unavoidable deviations

License

MIT