MCP CLI

MCP CLI is a tool for managing MCP server configuration files.

Why?

Model Context Protocol (MCP) is a new technology and still evolving. As I've been using it, I have encountered several pain points:

• Manually editing JSON files
• Managing similar config files for different AI tools
• Dealing with secret envvars
• Experimenting with new MCP servers
• Switching between different configurations based on what I'm doing (e.g., programming, writing, researching)

I decided to write up some specs for a tool (written in Go) that could help with these pain points and try to "vibe code" it. This is the result. Please don't judge the code quality. I didn't write or edit a single line :)

Installation

macOS and Linux

Download the appropriate binary for your platform from the [releases page](https://github.com/ jritsema/mcp-cli/releases):

• macOS AMD64: mcp-darwin-amd64
• macOS ARM64: mcp-darwin-arm64
• Linux AMD64: mcp-linux-amd64

Make the binary executable and move it to your PATH:

chmod +x mcp-darwin-arm64
sudo mv mcp-darwin-arm64 /usr/local/bin/mcp

Windows

Download the appropriate Windows binary for your architecture from the [releases page](https://github.com/ jritsema/mcp-cli/releases):

• Windows AMD64 (most common): mcp-windows-amd64.zip
• Windows ARM64 (Surface devices, ARM VMs): mcp-windows-arm64.zip

Installation Steps

1. Download the appropriate .zip file for your architecture
2. Extract the .exe file from the archive
3. Move mcp.exe to a directory in your PATH, or add the directory to your PATH

Usage

MCP CLI simplifies managing MCP server configurations through a YAML-based approach.

Getting Started

1. Create an mcp-compose.yml file with your MCP server configurations. You can place this file in either:
   • Your current working directory (for project-specific configurations)
   • $HOME/.config/mcp/mcp-compose.yml (for global configurations)

# For global configuration
mkdir -p ~/.config/mcp
cp ./mcp-compose.yml $HOME/.config/mcp/

2. Use the CLI to manage and deploy these configurations to your favorite AI tools

mcp set -t q-cli # or -t cursor, -t claude-desktop

Configuration File Resolution

MCP CLI automatically looks for configuration files in the following order:

1. Local directory: ./mcp-compose.yml in your current working directory
2. Global directory: $HOME/.config/mcp/mcp-compose.yml in your home config directory
3. Custom path: Use the -f flag to specify a custom location

This allows you to have project-specific MCP server configurations that override your global settings when working in specific directories.

# Uses local mcp-compose.yml if it exists, otherwise falls back to global
mcp ls

# Explicitly use a custom configuration file
mcp ls -f ./custom-mcp-compose.yml

Listing MCP Servers

View available MCP servers defined in your configuration:

# List default MCP servers
mcp ls

# List all MCP servers
mcp ls -a

# List servers with specific profile
mcp ls programming

# Show detailed information (command and env vars)
mcp ls -l

# Show executable command with expanded environment variables
mcp ls -c

# Use a custom configuration file
mcp ls -f ./custom-mcp-compose.yml

The -c flag outputs copy-paste ready commands with environment variables expanded and prepended inline. This is useful for AI agents or scripts that need to execute MCP servers directly. Note: This may expose sensitive data such as API keys.

The output format shows NAME, PROFILES, COMMAND, and ENVVARS columns.

Setting MCP Configurations

Deploy your MCP server configurations to supported tools:

# Set default servers for Amazon Q CLI
mcp set -t q-cli

# Set programming profile servers for Cursor
mcp set programming -t cursor

# Set a specific server for Claude Desktop
mcp set -t claude-desktop -s github

# Set programming profile servers for Kiro IDE
mcp set programming -t kiro

# Use a custom output location
mcp set -c /path/to/output/mcp.json

Checking Deployment Status

See which servers are deployed to which tools:

# Show deployment status across all tools
mcp ls -s

# Show status for a specific tool only
mcp ls -s -t cursor

# Show detailed status with server types
mcp ls -s -l

Example output:

NAME      PROFILES     Q-CLI   CLAUDE   CURSOR   KIRO
----      --------     -----   ------   ------   ----
time      default      ✓       ✗        ✓        ✗
github    programming  ✓       ✓        ~        ✗

Status indicators:

• ✓ - Server is configured and matches
• ✗ - Server is not configured
• ~ - Server is configured but differs from compose file
• ? - Unable to read tool config

Clearing MCP Configurations

Remove all MCP servers from a configuration:

# Clear all servers from Amazon Q CLI configuration
mcp clear -t q-cli

# Clear from a custom output location
mcp clear -c /path/to/output/mcp.json

Tool Shortcuts

MCP CLI supports these predefined tool shortcuts for popular AI tools:

• q-cli - Amazon Q CLI
  • macOS/Linux: $HOME/.aws/amazonq/mcp.json
  • Windows: %USERPROFILE%\.aws\amazonq\mcp.json
• claude-desktop - Claude Desktop
  • macOS: $HOME/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %USERPROFILE%\AppData\Roaming\Claude\claude_desktop_config.json
• cursor - Cursor IDE
  • macOS/Linux: $HOME/.cursor/mcp.json
  • Windows: %USERPROFILE%\.cursor\mcp.json
• kiro - Kiro IDE
  • macOS/Linux: $HOME/.kiro/settings/mcp.json
  • Windows: %USERPROFILE%\.kiro\settings\mcp.json

Setting Default AI Tool

Configure a default AI tool to avoid specifying -t each time:

# Set Amazon Q CLI as your default tool
mcp config set tool ~/.aws/amazonq/mcp.json

# Now you can simply run:
mcp set programming

# or to switch back to defaults
mcp set

Setting Container Tool

If you're using containers to run your MCP servers (by setting the image property), then MCP CLI will output docker run commands by default. If you're using a different container tool such as finch or podman, etc., then you can use the set container-tool command.

# Set a custom container tool (default is docker)
mcp config set container-tool finch

Profiles

Organize your MCP servers with profiles using the labels field in your mcp-compose.yml:

services:
  brave:
    image: mcp/brave-search
    environment:
      BRAVE_API_KEY: ${BRAVE_API_KEY}
    labels:
      mcp.profile: research

  github:
    command: npx -y @modelcontextprotocol/server-github
    labels:
      mcp.profile: programming

Then deploy only those servers:

mcp set programming -t claude-desktop

Services without the label are considered defaults.

Remote MCP Servers

MCP CLI supports remote MCP servers that use Streamable HTTP transport. Remote servers are identified by URLs starting with https:// or http:// in the command field.

MCP CLI supports two authentication methods for remote servers:

1. Headers-based authentication - For API keys and custom headers
2. OAuth 2.0 authentication - For client credentials flow

Headers-Based Authentication

For remote servers that use API keys or custom headers (like Context7), use mcp.header.* labels:

services:
  context7:
    command: https://mcp.context7.com/mcp
    labels:
      mcp.header.Authorization: Bearer ${CONTEXT7_API_KEY}

  # Multiple headers example
  custom-server:
    command: https://api.example.com/mcp
    labels:
      mcp.header.X-API-Key: ${API_KEY}
      mcp.header.X-Custom-Header: some-value

The header name is everything after mcp.header. - so mcp.header.Authorization becomes the Authorization header. Environment variables in header values are automatically expanded.

OAuth 2.0 Authentication

For remote servers that use OAuth 2.0 client credentials flow:

services:
  my-remote-server:
    command: https://my-remote-server.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp
    labels:
      mcp.grant-type: client_credentials
      mcp.token-endpoint: https://my-app.auth.us-east-1.amazoncognito.com/oauth2/token
      mcp.client-id: ${REMOTE_CLIENT_ID}
      mcp.client-secret: ${REMOTE_CLIENT_SECRET}

Required OAuth Labels:

• mcp.grant-type: Must be "client_credentials"
• mcp.token-endpoint: OAuth 2.0 token endpoint URL
• mcp.client-id: OAuth client identifier (supports environment variable expansion)
• mcp.client-secret: OAuth client secret (supports environment variable expansion)

Environment Variables

Set your credentials in your environment or .env file:

# For headers-based auth
CONTEXT7_API_KEY=your_api_key_here

# For OAuth
REMOTE_CLIENT_ID=your_client_id_here
REMOTE_CLIENT_SECRET=your_client_secret_here

Tool Support

Remote MCP servers are currently supported by:

• cursor - Cursor IDE
• kiro - Kiro IDE
• q-cli - Amazon Q CLI

Authentication Flow

When deploying remote servers, MCP CLI will:

For headers-based auth:

1. Extract headers from mcp.header.* labels
2. Expand environment variables in header values
3. Generate MCP configuration with HTTP transport and headers

For OAuth:

1. Validate the OAuth configuration
2. Acquire an access token using the client credentials flow
3. Generate MCP configuration with HTTP transport and authorization headers

# Deploy remote servers
mcp set -t cursor

How?

It turns out that the Docker Compose (docker-compose.yml) specification already has good support for MCP stdio configuration where services map to MCP servers with commands, images, environments/env_filess, and labels for profiles. Another added benefit of this is you can run docker compose pull -f mcp-compose.yml and it will pre-fetch all the container images.

Example:

# MCP Servers
services:
  time:
    command: uvx mcp-server-time

  fetch:
    command: uvx mcp-server-fetch

  github:
    command: npx -y @modelcontextprotocol/server-github
    environment:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PERSONAL_ACCESS_TOKEN}
    labels:
      mcp.profile: programming

  aws-docs:
    command: uvx awslabs.aws-documentation-mcp-server@latest
    environment:
      FASTMCP_LOG_LEVEL: "ERROR"
    labels:
      mcp.profile: programming

  postgres:
    command: npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb
    labels:
      mcp.profile: database

  # OR container based MCP servers

  github-docker:
    image: ghcr.io/github/github-mcp-server
    environment:
      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PERSONAL_ACCESS_TOKEN}
    labels:
      mcp.profile: programming

  brave:
    image: mcp/brave-search
    environment:
      BRAVE_API_KEY: ${BRAVE_API_KEY}
    labels:
      mcp.profile: programming, research

  # Container with volume mounts
  filesystem:
    image: mcp/filesystem
    volumes:
      - ${HOME}/projects:/workspace:ro
      - /tmp:/tmp
    labels:
      mcp.profile: programming

Development

 Choose a make command to run

  vet           vet code
  test          run unit tests
  build         build a binary
  autobuild     auto build when source files change
  dockerbuild   build project into a docker container image
  build-all     build binaries for all platforms
  start         build and run local project
  deploy        build code into a container and deploy it to the cloud dev environment