{"id":31581017,"url":"https://github.com/cearley/claude-extend","last_synced_at":"2026-05-17T15:39:20.832Z","repository":{"id":315640253,"uuid":"1060222389","full_name":"cearley/claude-extend","owner":"cearley","description":"A CLI tool for managing MCP server connections with Claude Code","archived":false,"fork":false,"pushed_at":"2025-09-22T23:27:03.000Z","size":117,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T21:55:27.547Z","etag":null,"topics":["claude-code","mcp-tools"],"latest_commit_sha":null,"homepage":"","language":"Python","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/cearley.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-09-19T15:05:11.000Z","updated_at":"2025-09-22T23:26:57.000Z","dependencies_parsed_at":"2025-09-19T21:09:49.008Z","dependency_job_id":"2b57312c-31e7-4c93-82a6-1359944dae50","html_url":"https://github.com/cearley/claude-extend","commit_stats":null,"previous_names":["cearley/claude-extend"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cearley/claude-extend","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cearley%2Fclaude-extend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cearley%2Fclaude-extend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cearley%2Fclaude-extend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cearley%2Fclaude-extend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cearley","download_url":"https://codeload.github.com/cearley/claude-extend/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cearley%2Fclaude-extend/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33143647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T09:28:26.183Z","status":"ssl_error","status_checked_at":"2026-05-17T09:27:52.702Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["claude-code","mcp-tools"],"created_at":"2025-10-05T21:52:07.098Z","updated_at":"2026-05-17T15:39:20.826Z","avatar_url":"https://github.com/cearley.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude eXtend (cx)\n\n[![CI](https://github.com/cearley/claude-extend/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/cearley/claude-extend/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/badge/coverage-86%25-brightgreen)](https://github.com/cearley/claude-extend/actions/workflows/ci.yml)\n[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![Release](https://img.shields.io/github/release/cearley/claude-extend.svg)](https://github.com/cearley/claude-extend/releases/latest)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub last commit](https://img.shields.io/github/last-commit/cearley/claude-extend)](https://github.com/cearley/claude-extend/commits/main)\n\nA CLI tool for managing Model Context Protocol (MCP) server connections with Claude Code.\n\nClaude eXtend allows you to easily add, remove, and manage MCP servers that extend Claude Code's capabilities. It comes with opinionated default MCP tool definitions and can dynamically install servers (e.g., via npx or uvx) or work with pre-installed servers. The default tool definitions can be overridden or extended via external configuration files.\n\n## Quick Start\n\nRun `cx` instantly with `uvx` directly from GitHub (no installation required):\n\n```bash\n# List available MCP tools (always gets latest release)\nuvx --from git+https://github.com/cearley/claude-extend@latest cx list\n\n# Add basic-memory MCP server to Claude Code\nuvx --from git+https://github.com/cearley/claude-extend@latest cx add basic-memory\n\n# Interactive mode for guided tool selection\nuvx --from git+https://github.com/cearley/claude-extend@latest cx add --interactive\n```\n\nOr install locally from GitHub:\n\n```bash\n# Install latest release\nuv tool install git+https://github.com/cearley/claude-extend@latest\ncx list\ncx add basic-memory\n```\n\n\u003e 💡 **Tip**: Using `@latest` ensures you always get the most recent stable release. You can also use specific versions like `@v0.2.0` if needed.\n\nOr install from source:\n\n```bash\ngit clone https://github.com/cearley/claude-extend.git\ncd claude-extend\nuv tool install .\ncx add --interactive\n```\n\n## Table of Contents\n\n- [Why use cx instead of `claude mcp` directly?](#why-use-cx-instead-of-claude-mcp-directly)\n- [Usage](#usage)\n  - [Interactive Mode](#interactive-mode)\n- [External Configuration](#external-configuration)\n  - [Configuration File Locations](#configuration-file-locations)\n  - [Configuration File Format](#configuration-file-format)\n  - [Example: Adding basic-memory](#example-adding-basic-memory)\n- [What are MCP Servers?](#what-are-mcp-servers)\n- [Security Considerations](#security-considerations)\n- [Requirements](#requirements)\n- [Development](#development)\n- [License](#license)\n\n## Why use cx instead of `claude mcp` directly?\n\nThe main benefit of `cx` is **organization**: your selected MCP tools are codified in a configuration file, making them easy to add, remove, and share:\n\n- **📝 Codified setup**: Your MCP tools are defined in a JSON config with exact installation commands\n- **🔄 Reproducible**: Share your `tools.json` with teammates or across machines\n- **🎯 Curated collection**: Maintain a focused set of tools relevant to your workflow\n- **⚡ Quick access**: Add/remove tools by name without remembering complex installation syntax\n\nWhile `claude mcp add` works fine for one-off installations, `cx` helps when you want to maintain and organize a consistent set of MCP tools over time.\n\n## Usage\n\n```bash\ncx                    # Show help and available commands\ncx list              # List available MCP tools\ncx add \u003ctool\u003e        # Add an MCP tool to Claude Code\ncx add --interactive # Interactive tool selection menu\ncx remove \u003ctool\u003e     # Remove an MCP tool from Claude Code\n```\n\n### Interactive Mode\n\nFor a guided experience, use interactive mode to select and install multiple tools:\n\n```bash\ncx add --interactive\n```\n\nInteractive mode provides:\n- 📋 List of all available tools with installation status\n- 🎯 Multi-select tool installation\n- ✅ Prerequisites checking before installation\n- 📦 Batch installation of selected tools\n\n## External Configuration\n\nClaude eXtend can load custom MCP tool definitions from an external configuration file. This allows you to add your own MCP servers without modifying the source code.\n\n### Configuration File Locations\n\nClaude eXtend checks for configuration files in this order:\n\n1. **Environment variable**: `CLAUDE_EXTEND_CONFIG` (full path to config file)\n2. **User config directory**: `~/.config/claude-extend/tools.json`\n3. **Home directory**: `~/.claude-extend/tools.json`\n\n### Configuration File Format\n\nCreate a JSON file with the following structure:\n\n```json\n{\n  \"tools\": {\n    \"my-custom-server\": {\n      \"description\": \"My custom MCP server\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"my-custom-server\"]\n    }\n  }\n}\n```\n\nThe format matches Claude Desktop's MCP configuration:\n- **Tool name**: Derived from the JSON key (no separate `name` field needed)\n- **description**: Human-readable description of the tool\n- **command**: The executable command (e.g., `npx`, `uvx`, `python`)\n- **args**: Array of command arguments, supports `{project_dir}` placeholder\n\n### Example: Adding basic-memory\n\nThis example shows how to add [basic-memory](https://github.com/basicmachines-co/basic-memory), an AI-powered memory system, to your Claude eXtend configuration.\n\n**Step 1: Install basic-memory**\n\nFirst, install basic-memory on your system ([installation guide](https://docs.basicmemory.com/getting-started/#installation)):\n\n```bash\ncurl -LsSf https://basicmemory.com/install/latest.sh | sh\n```\n\n**Step 2: Create external configuration**\n\nCreate a configuration file to tell Claude eXtend about basic-memory:\n\n```bash\n# Create config directory\nmkdir -p ~/.config/claude-extend\n\n# Create your tools.json file\ncat \u003e ~/.config/claude-extend/tools.json \u003c\u003c 'EOF'\n{\n  \"tools\": {\n    \"basic-memory\": {\n      \"description\": \"AI-powered memory system for contextual understanding\",\n      \"command\": \"basic-memory\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\nEOF\n```\n\n**Step 3: Use with Claude eXtend**\n\nNow basic-memory will appear in your available tools:\n\n```bash\n# List available tools (basic-memory should now appear)\ncx list\n\n# Add basic-memory to Claude Code\ncx add basic-memory\n```\n\n**How it works:**\n\n- Claude eXtend automatically checks if the `basic-memory` command is available in your system PATH before attempting to add it\n- After running the installation script, `basic-memory` becomes a valid system command that can be executed from anywhere\n- Claude eXtend uses Python's `shutil.which()` to verify the command exists before proceeding\n- The `command` and `args` fields define how to execute the MCP server (equivalent to running `basic-memory mcp`)\n\nWhen you run `cx add basic-memory`, Claude eXtend will first check that the `basic-memory` command is available, then execute `claude mcp add basic-memory -- basic-memory mcp` to configure Claude Code with the basic-memory MCP server.\n\n## What are MCP Servers?\n\nModel Context Protocol (MCP) servers extend Claude Code's capabilities by providing additional tools and context. Examples include:\n\n- File system access tools\n- Database connection tools\n- API integration tools\n- Development environment tools\n\nClaude eXtend helps you manage which of these installed servers are active in your Claude Code setup.\n\n## Security Considerations\n\n⚠️ **Important**: The `command` and `args` entries in external `tools.json` configuration files define commands that are executed directly on your machine. Only use configuration files from trusted sources, and always review their contents before use. Treat these files like any other script - they should be reviewed and trusted before execution.\n\n## Requirements\n\n- Python 3.8+\n- `uv` package manager (for `uvx` usage)\n\n## Development\n\nSee [CLAUDE.md](CLAUDE.md) for development guidance.\n\n## Development Notes\n\nThis project utilized AI assistance, specifically Claude, for certain aspects of its development, including:\n\n- Generating initial code structures and CLI architecture\n- Implementing comprehensive test suites with proper mocking strategies\n- Drafting and refining documentation sections\n- Assisting with debugging, performance optimization, and problem-solving\n- Code review and best practices recommendations\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcearley%2Fclaude-extend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcearley%2Fclaude-extend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcearley%2Fclaude-extend/lists"}