https://github.com/jritsema/mcp-cli
MCP CLI is a tool for managing MCP server configuration files
https://github.com/jritsema/mcp-cli
cli mcp mcp-cli mcpserver
Last synced: 11 days ago
JSON representation
MCP CLI is a tool for managing MCP server configuration files
- Host: GitHub
- URL: https://github.com/jritsema/mcp-cli
- Owner: jritsema
- License: mit
- Created: 2025-05-03T17:12:35.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-01-22T21:36:20.000Z (22 days ago)
- Last Synced: 2026-01-23T14:23:46.077Z (22 days ago)
- Topics: cli, mcp, mcp-cli, mcpserver
- Language: Go
- Homepage: https://johnritsema.com/posts/mcp-cli
- Size: 128 KB
- Stars: 11
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```sh
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](./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)
```sh
# 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
```sh
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.
```sh
# 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:
```sh
# 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:
```sh
# 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:
```sh
# 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:
```sh
# 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:
```sh
# 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.
```sh
# 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`:
```yaml
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:
```sh
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](https://context7.com)), use `mcp.header.*` labels:
```yaml
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:
```yaml
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:
```bash
# 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
```sh
# 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 `command`s, `image`s, `environment`s/`env_files`s, and `label`s 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:
```yaml
# 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
```