{"id":32460286,"url":"https://github.com/jritsema/mcp-cli","last_synced_at":"2026-02-03T04:08:57.418Z","repository":{"id":299165823,"uuid":"977210178","full_name":"jritsema/mcp-cli","owner":"jritsema","description":"MCP CLI is a tool for managing MCP server configuration files","archived":false,"fork":false,"pushed_at":"2026-01-22T21:36:20.000Z","size":131,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-23T14:23:46.077Z","etag":null,"topics":["cli","mcp","mcp-cli","mcpserver"],"latest_commit_sha":null,"homepage":"https://johnritsema.com/posts/mcp-cli","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jritsema.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-03T17:12:35.000Z","updated_at":"2026-01-22T21:35:15.000Z","dependencies_parsed_at":"2025-06-15T04:28:40.198Z","dependency_job_id":"db0b71b6-9911-441e-9f01-aa0d4d0e9703","html_url":"https://github.com/jritsema/mcp-cli","commit_stats":null,"previous_names":["jritsema/mcp-cli"],"tags_count":13,"template":false,"template_full_name":"jritsema/go-template","purl":"pkg:github/jritsema/mcp-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jritsema%2Fmcp-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jritsema%2Fmcp-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jritsema%2Fmcp-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jritsema%2Fmcp-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jritsema","download_url":"https://codeload.github.com/jritsema/mcp-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jritsema%2Fmcp-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29032185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T02:28:16.591Z","status":"ssl_error","status_checked_at":"2026-02-03T02:27:48.904Z","response_time":96,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","mcp","mcp-cli","mcpserver"],"created_at":"2025-10-26T11:53:19.553Z","updated_at":"2026-02-03T04:08:57.402Z","avatar_url":"https://github.com/jritsema.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP CLI\n\nMCP CLI is a tool for managing MCP server configuration files.\n\n## Why?\n\nModel Context Protocol (MCP) is a new technology and still evolving. As I've been using it, I have encountered several pain points:\n\n- Manually editing JSON files\n- Managing similar config files for different AI tools\n- Dealing with secret envvars\n- Experimenting with new MCP servers\n- Switching between different configurations based on what I'm doing (e.g., programming, writing, researching)\n\nI 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 :)\n\n## Installation\n\n### macOS and Linux\n\nDownload the appropriate binary for your platform from the [releases page](https://github.com/\njritsema/mcp-cli/releases):\n\n- macOS AMD64: `mcp-darwin-amd64`\n- macOS ARM64: `mcp-darwin-arm64`\n- Linux AMD64: `mcp-linux-amd64`\n\nMake the binary executable and move it to your PATH:\n\n```sh\nchmod +x mcp-darwin-arm64\nsudo mv mcp-darwin-arm64 /usr/local/bin/mcp\n```\n\n### Windows\n\nDownload the appropriate Windows binary for your architecture from the [releases page](https://github.com/\njritsema/mcp-cli/releases):\n\n- **Windows AMD64** (most common): `mcp-windows-amd64.zip`\n- **Windows ARM64** (Surface devices, ARM VMs): `mcp-windows-arm64.zip`\n\n#### Installation Steps\n\n1. Download the appropriate `.zip` file for your architecture\n2. Extract the `.exe` file from the archive\n3. Move `mcp.exe` to a directory in your PATH, or add the directory to your PATH\n\n## Usage\n\nMCP CLI simplifies managing MCP server configurations through a YAML-based approach.\n\n### Getting Started\n\n1. Create an [mcp-compose.yml](./mcp-compose.yml) file with your MCP server configurations. You can place this file in either:\n   - Your current working directory (for project-specific configurations)\n   - `$HOME/.config/mcp/mcp-compose.yml` (for global configurations)\n\n```sh\n# For global configuration\nmkdir -p ~/.config/mcp\ncp ./mcp-compose.yml $HOME/.config/mcp/\n```\n\n2. Use the CLI to manage and deploy these configurations to your favorite AI tools\n\n```sh\nmcp set -t q-cli # or -t cursor, -t claude-desktop\n```\n\n### Configuration File Resolution\n\nMCP CLI automatically looks for configuration files in the following order:\n\n1. **Local directory**: `./mcp-compose.yml` in your current working directory\n2. **Global directory**: `$HOME/.config/mcp/mcp-compose.yml` in your home config directory\n3. **Custom path**: Use the `-f` flag to specify a custom location\n\nThis allows you to have project-specific MCP server configurations that override your global settings when working in specific directories.\n\n```sh\n# Uses local mcp-compose.yml if it exists, otherwise falls back to global\nmcp ls\n\n# Explicitly use a custom configuration file\nmcp ls -f ./custom-mcp-compose.yml\n```\n\n### Listing MCP Servers\n\nView available MCP servers defined in your configuration:\n\n```sh\n# List default MCP servers\nmcp ls\n\n# List all MCP servers\nmcp ls -a\n\n# List servers with specific profile\nmcp ls programming\n\n# Show detailed information (command and env vars)\nmcp ls -l\n\n# Show executable command with expanded environment variables\nmcp ls -c\n\n# Use a custom configuration file\nmcp ls -f ./custom-mcp-compose.yml\n```\n\nThe `-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.\n\nThe output format shows NAME, PROFILES, COMMAND, and ENVVARS columns.\n\n### Setting MCP Configurations\n\nDeploy your MCP server configurations to supported tools:\n\n```sh\n# Set default servers for Amazon Q CLI\nmcp set -t q-cli\n\n# Set programming profile servers for Cursor\nmcp set programming -t cursor\n\n# Set a specific server for Claude Desktop\nmcp set -t claude-desktop -s github\n\n# Set programming profile servers for Kiro IDE\nmcp set programming -t kiro\n\n# Use a custom output location\nmcp set -c /path/to/output/mcp.json\n```\n\n### Checking Deployment Status\n\nSee which servers are deployed to which tools:\n\n```sh\n# Show deployment status across all tools\nmcp ls -s\n\n# Show status for a specific tool only\nmcp ls -s -t cursor\n\n# Show detailed status with server types\nmcp ls -s -l\n```\n\nExample output:\n\n```\nNAME      PROFILES     Q-CLI   CLAUDE   CURSOR   KIRO\n----      --------     -----   ------   ------   ----\ntime      default      ✓       ✗        ✓        ✗\ngithub    programming  ✓       ✓        ~        ✗\n```\n\nStatus indicators:\n\n- `✓` - Server is configured and matches\n- `✗` - Server is not configured\n- `~` - Server is configured but differs from compose file\n- `?` - Unable to read tool config\n\n### Clearing MCP Configurations\n\nRemove all MCP servers from a configuration:\n\n```sh\n# Clear all servers from Amazon Q CLI configuration\nmcp clear -t q-cli\n\n# Clear from a custom output location\nmcp clear -c /path/to/output/mcp.json\n```\n\n### Tool Shortcuts\n\nMCP CLI supports these predefined tool shortcuts for popular AI tools:\n\n- `q-cli` - Amazon Q CLI\n  - macOS/Linux: `$HOME/.aws/amazonq/mcp.json`\n  - Windows: `%USERPROFILE%\\.aws\\amazonq\\mcp.json`\n- `claude-desktop` - Claude Desktop\n  - macOS: `$HOME/Library/Application Support/Claude/claude_desktop_config.json`\n  - Windows: `%USERPROFILE%\\AppData\\Roaming\\Claude\\claude_desktop_config.json`\n- `cursor` - Cursor IDE\n  - macOS/Linux: `$HOME/.cursor/mcp.json`\n  - Windows: `%USERPROFILE%\\.cursor\\mcp.json`\n- `kiro` - Kiro IDE\n  - macOS/Linux: `$HOME/.kiro/settings/mcp.json`\n  - Windows: `%USERPROFILE%\\.kiro\\settings\\mcp.json`\n\n### Setting Default AI Tool\n\nConfigure a default AI tool to avoid specifying `-t` each time:\n\n```sh\n# Set Amazon Q CLI as your default tool\nmcp config set tool ~/.aws/amazonq/mcp.json\n\n# Now you can simply run:\nmcp set programming\n\n# or to switch back to defaults\nmcp set\n```\n\n### Setting Container Tool\n\nIf 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.\n\n```sh\n# Set a custom container tool (default is docker)\nmcp config set container-tool finch\n```\n\n### Profiles\n\nOrganize your MCP servers with profiles using the `labels` field in your `mcp-compose.yml`:\n\n```yaml\nservices:\n  brave:\n    image: mcp/brave-search\n    environment:\n      BRAVE_API_KEY: ${BRAVE_API_KEY}\n    labels:\n      mcp.profile: research\n\n  github:\n    command: npx -y @modelcontextprotocol/server-github\n    labels:\n      mcp.profile: programming\n```\n\nThen deploy only those servers:\n\n```sh\nmcp set programming -t claude-desktop\n```\n\nServices without the label are considered defaults.\n\n### Remote MCP Servers\n\nMCP 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.\n\nMCP CLI supports two authentication methods for remote servers:\n\n1. **Headers-based authentication** - For API keys and custom headers\n2. **OAuth 2.0 authentication** - For client credentials flow\n\n#### Headers-Based Authentication\n\nFor remote servers that use API keys or custom headers (like [Context7](https://context7.com)), use `mcp.header.*` labels:\n\n```yaml\nservices:\n  context7:\n    command: https://mcp.context7.com/mcp\n    labels:\n      mcp.header.Authorization: Bearer ${CONTEXT7_API_KEY}\n\n  # Multiple headers example\n  custom-server:\n    command: https://api.example.com/mcp\n    labels:\n      mcp.header.X-API-Key: ${API_KEY}\n      mcp.header.X-Custom-Header: some-value\n```\n\nThe header name is everything after `mcp.header.` - so `mcp.header.Authorization` becomes the `Authorization` header. Environment variables in header values are automatically expanded.\n\n#### OAuth 2.0 Authentication\n\nFor remote servers that use OAuth 2.0 client credentials flow:\n\n```yaml\nservices:\n  my-remote-server:\n    command: https://my-remote-server.gateway.bedrock-agentcore.us-east-1.amazonaws.com/mcp\n    labels:\n      mcp.grant-type: client_credentials\n      mcp.token-endpoint: https://my-app.auth.us-east-1.amazoncognito.com/oauth2/token\n      mcp.client-id: ${REMOTE_CLIENT_ID}\n      mcp.client-secret: ${REMOTE_CLIENT_SECRET}\n```\n\n**Required OAuth Labels:**\n\n- `mcp.grant-type`: Must be \"client_credentials\"\n- `mcp.token-endpoint`: OAuth 2.0 token endpoint URL\n- `mcp.client-id`: OAuth client identifier (supports environment variable expansion)\n- `mcp.client-secret`: OAuth client secret (supports environment variable expansion)\n\n#### Environment Variables\n\nSet your credentials in your environment or `.env` file:\n\n```bash\n# For headers-based auth\nCONTEXT7_API_KEY=your_api_key_here\n\n# For OAuth\nREMOTE_CLIENT_ID=your_client_id_here\nREMOTE_CLIENT_SECRET=your_client_secret_here\n```\n\n#### Tool Support\n\nRemote MCP servers are currently supported by:\n\n- `cursor` - Cursor IDE\n- `kiro` - Kiro IDE\n- `q-cli` - Amazon Q CLI\n\n#### Authentication Flow\n\nWhen deploying remote servers, MCP CLI will:\n\n**For headers-based auth:**\n\n1. Extract headers from `mcp.header.*` labels\n2. Expand environment variables in header values\n3. Generate MCP configuration with HTTP transport and headers\n\n**For OAuth:**\n\n1. Validate the OAuth configuration\n2. Acquire an access token using the client credentials flow\n3. Generate MCP configuration with HTTP transport and authorization headers\n\n```sh\n# Deploy remote servers\nmcp set -t cursor\n```\n\n## How?\n\nIt 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.\n\nExample:\n\n```yaml\n# MCP Servers\nservices:\n  time:\n    command: uvx mcp-server-time\n\n  fetch:\n    command: uvx mcp-server-fetch\n\n  github:\n    command: npx -y @modelcontextprotocol/server-github\n    environment:\n      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PERSONAL_ACCESS_TOKEN}\n    labels:\n      mcp.profile: programming\n\n  aws-docs:\n    command: uvx awslabs.aws-documentation-mcp-server@latest\n    environment:\n      FASTMCP_LOG_LEVEL: \"ERROR\"\n    labels:\n      mcp.profile: programming\n\n  postgres:\n    command: npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb\n    labels:\n      mcp.profile: database\n\n  # OR container based MCP servers\n\n  github-docker:\n    image: ghcr.io/github/github-mcp-server\n    environment:\n      GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_PERSONAL_ACCESS_TOKEN}\n    labels:\n      mcp.profile: programming\n\n  brave:\n    image: mcp/brave-search\n    environment:\n      BRAVE_API_KEY: ${BRAVE_API_KEY}\n    labels:\n      mcp.profile: programming, research\n\n  # Container with volume mounts\n  filesystem:\n    image: mcp/filesystem\n    volumes:\n      - ${HOME}/projects:/workspace:ro\n      - /tmp:/tmp\n    labels:\n      mcp.profile: programming\n```\n\n## Development\n\n```\n Choose a make command to run\n\n  vet           vet code\n  test          run unit tests\n  build         build a binary\n  autobuild     auto build when source files change\n  dockerbuild   build project into a docker container image\n  build-all     build binaries for all platforms\n  start         build and run local project\n  deploy        build code into a container and deploy it to the cloud dev environment\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjritsema%2Fmcp-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjritsema%2Fmcp-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjritsema%2Fmcp-cli/lists"}