mcp2cli — Using MCP Servers as CLI

mcp2cli solves a real problem: MCP (Model Context Protocol) schemas are a hundred times more bloated than necessary. A simple GitHub API normally requires 15-25 KB per turn. With mcp2cli: 150-200 bytes.

The Token Problem

Native MCP (Standard)

When you add an MCP server, Claude injects this every time:

{
  "type": "resource",
  "uri": "github://repositories",
  "description": "GitHub Repository Management",
  "mimeType": "application/json",
  "contents": "[MASSIVE SCHEMA] ~18KB",
  "capabilities": [
    "list",
    "get",
    "create",
    "update",
    "delete"
  ],
  "tools": [
    {
      "name": "github_list_repos",
      "description": "...",
      "inputSchema": {
        "type": "object",
        "properties": {...},
        "required": [...]
      }
    },
    {...more tools...}
  ]
}

Per Turn: 15-25 KB for every single message.

With 10 tools: ~250 KB just for schema definitions. That's expensive and slow.

With mcp2cli

/github list-repos --owner=anthropics --limit=10

Claude sees only:

Available command: github list-repos
Parameters: --owner (string, required), --limit (number, optional, max 100)

Per Turn: 200-400 bytes.

Token Savings: 96-99%.

Installation

Option 1: Python Package

pip install mcp2cli

Option 2: As Claude Code Plugin

# GitHub variant by myeolinmalchi
claude plugin add github:myeolinmalchi/mcp2cli

# Then immediately available in workflow
/mcp2cli "GitHub list repos"

Option 3: Docker

docker run -p 5000:5000 knowsuchagency/mcp2cli:latest

Three Operating Modes

Mode 1: MCP → CLI

Original MCP server becomes CLI interface.

Input: MCP Server with 50+ tools Output: CLI with autocomplete commands Token Reduction: ~97%

Example:

# Start mcp2cli with GitHub MCP
mcp2cli serve --mcp-url http://localhost:5678/github

# Then in Claude Code:
/github list-repos --org anthropics --sort stars
/github create-issue --title "Bug in foo" --body "Details"

Mode 2: OpenAPI → CLI

Convert OpenAPI specs directly to CLI.

Input: OpenAPI Spec (e.g., from swagger.io) Output: CLI with full tool documentation

Example:

mcp2cli convert openapi \
  https://api.github.com/repos/anthropics/claude-code/openapi.json \
  --output github-cli.json

Mode 3: GraphQL → CLI

GraphQL server to CLI.

mcp2cli convert graphql \
  https://api.github.com/graphql \
  --auth-token $GITHUB_TOKEN

Baking Configs — Store Credentials

Problem: Credentials on every call?

/mcp2cli --auth-token $GITHUB_TOKEN "list repos"
/mcp2cli --auth-token $GITHUB_TOKEN "create issue"  # again?

Solution: Baking Config

# Create config
mcp2cli bake-config github \
  --auth-token $GITHUB_TOKEN \
  --base-url https://api.github.com \
  --output ~/.mcp2cli/github-config.json

# Then just:
/github list-repos

Save Configuration

~/.mcp2cli/config.json:

{
  "mcp_servers": [
    {
      "name": "github",
      "type": "mcp",
      "url": "http://localhost:5678",
      "auth": {
        "type": "bearer",
        "token": "${GITHUB_TOKEN}"
      }
    },
    {
      "name": "stripe",
      "type": "openapi",
      "url": "https://api.stripe.com/openapi.json",
      "auth": {
        "type": "api_key",
        "key": "${STRIPE_API_KEY}"
      }
    }
  ]
}

Automatically loaded.

OAuth 2.1 Integration

For services requiring OAuth (GitHub, Google, Stripe):

# Interactive setup
mcp2cli auth setup github

# Asks for:
# 1. Client ID
# 2. Client Secret
# 3. Authorizes in browser
# 4. Securely stores token

# Then use:
/github list-repos

How is token stored?

Safely in ~/.mcp2cli/credentials/:

ls -la ~/.mcp2cli/credentials/
# github-oauth.enc
# stripe-api-key.enc
# (all encrypted)

Tool Filtering — Performance Tuning

Problem: 50+ tools, you only need 3

Native MCP injects all 50 tools with every message.

Solution: --tools Flag

mcp2cli serve \
  --mcp-url http://localhost:5678 \
  --tools "list_repos,create_issue,get_user"

Only these 3 are available to Claude.

Additional token savings 70-80% (vs. all 50).

Dynamic Tool Filtering

# For GitHub: only "read" operations
mcp2cli serve \
  --mcp-url github \
  --tools-filter "operation:read"

# Only a specific team
mcp2cli serve \
  --mcp-url github \
  --filter "scope:team-engineering"

Practical Examples

Example 1: GitHub Workflow Integration

# Start mcp2cli with GitHub MCP
mcp2cli serve \
  --mcp-url http://localhost:5678/github \
  --tools "list_repos,get_repo,create_pr,get_issue"

# In Claude Code then:
/github list_repos --org mycompany --type private
# → "Found 47 private repos"

/github get_repo mycompany/platform
# → Repository details...

/github create_pr \
  --repo platform \
  --title "Feature: Add CLI support" \
  --branch feature/cli

Example 2: Stripe Payment API

mcp2cli convert openapi \
  https://files.readme.io/6d6f58c-openapi.json \
  --name stripe \
  --auth-token $STRIPE_API_KEY

# Then in Claude Code:
/stripe create_customer \
  --email [email protected] \
  --name "John Doe"

/stripe create_payment_intent \
  --amount 2999 \
  --currency usd \
  --customer {customer_id}

Example 3: Multi-Service Setup

{
  "services": [
    {
      "name": "github",
      "mcp_url": "http://localhost:5678/github",
      "tools": "read_*,list_*"
    },
    {
      "name": "slack",
      "openapi_url": "https://slack.com/api/openapi.json",
      "tools": "chat_postMessage,conversations_list"
    },
    {
      "name": "postgres",
      "mcp_url": "postgresql://localhost:5432/mydb",
      "tools": "query,execute,describe_table"
    }
  ]
}

Token Reduction in Practice

Scenario: GitHub + Stripe Integration

Native MCP:

GitHub MCP: 18 KB/Turn × 15 Tools
Stripe OpenAPI: 22 KB/Turn × 30 Tools
Per Turn: ~40 KB just for schemas

With 100 turns in one session: 4 MB just for tool definitions.

Cost at $0.003/1K input tokens:

Raw MCP: ~$0.012 per 100-turn session
With mcp2cli (filtered): ~$0.0005 per session

24× cheaper.

Speed:

Raw MCP: ~800ms processing per turn (due to large schemas)
With mcp2cli: ~50ms processing per turn

16× faster.

Token Comparison Table

Scenario	Raw MCP	With mcp2cli	Reduction
GitHub (15 Tools)	18 KB	200 B	99%
Stripe (30 Tools)	22 KB	350 B	98%
PostgreSQL (50 Queries)	35 KB	400 B	99%
Multi-Service (3×50 Tools)	120 KB	900 B	99%

Installation & Setup Quick Start

Step 1: Install mcp2cli

pip install mcp2cli
# or as plugin
claude plugin add github:myeolinmalchi/mcp2cli

Step 2: Start MCP Server

# Example with GitHub MCP
mcp2cli serve \
  --mcp-url http://localhost:5678 \
  --tools "list_repos,create_issue"

Step 3: Use in Claude Code

/mcp2cli "List all my repositories"
/mcp2cli "Create an issue titled 'Bug: xyz'"

Step 4: Save Credentials

mcp2cli bake-config github \
  --auth-token $GITHUB_TOKEN

Step 5: Test & Go

# Test the connection
mcp2cli health-check

# Should return:
# ✓ GitHub MCP: Connected
# ✓ Token: Valid
# ✓ Rate limit: 5000 remaining

mcp2cli vs Native MCP

Aspect	Native MCP	mcp2cli
Token Size	15-25 KB	200-400 B
Token Reduction	—	96-99%
Speed	~800ms	~50ms
Setup Complexity	Medium	Simple
Error Handling	Automatic	Manually configured
OAuth Support	Limited	Full
Tool Filtering	No	Yes
Credentials Management	Ad-hoc	Preconfigured
Best For	Simple APIs	Production, Scale

Common Issues

Issue 1: "No tools found"

Cause: mcp2cli cannot reach server

Solution:

# Debug
mcp2cli debug --mcp-url http://localhost:5678

# Or:
curl http://localhost:5678/health

Issue 2: Token invalid

Cause: OAuth token expired

Solution:

mcp2cli auth refresh github
# Or completely new
mcp2cli auth setup github

Issue 3: Tool not visible

Cause: Tool is filtered

Solution:

# Show currently available tools
mcp2cli list-tools

# Include all tools too
mcp2cli serve \
  --mcp-url http://localhost:5678 \
  --show-all-tools

Performance Best Practices

Filter tools aggressively: Only use tools you need
Bake credentials: Don't re-authenticate on every call
Multi-service setup: Configure all APIs centrally
Rate limiting: Set --rate-limit 100/min
Monitoring: Run mcp2cli monitor in background

The Token Problem

Native MCP (Standard)

With mcp2cli

Installation

Option 1: Python Package

Option 2: As Claude Code Plugin

Option 3: Docker

Three Operating Modes

Mode 1: MCP → CLI

Mode 2: OpenAPI → CLI

Mode 3: GraphQL → CLI

Baking Configs — Store Credentials

Problem: Credentials on every call?

Save Configuration

OAuth 2.1 Integration

How is token stored?

Tool Filtering — Performance Tuning

Problem: 50+ tools, you only need 3

Dynamic Tool Filtering

Practical Examples

Example 1: GitHub Workflow Integration

Example 2: Stripe Payment API

Example 3: Multi-Service Setup

Token Reduction in Practice

Scenario: GitHub + Stripe Integration

Token Comparison Table

Installation & Setup Quick Start

Step 1: Install mcp2cli

Step 2: Start MCP Server

Step 3: Use in Claude Code

Step 4: Save Credentials

Step 5: Test & Go

mcp2cli vs Native MCP

Common Issues

Issue 1: "No tools found"

Issue 2: Token invalid

Issue 3: Tool not visible

Performance Best Practices

Sources and Links

Continue the learning path