npm package: @feli0x/mcps
Description: CLI for managing MCP servers
Latest version: 0.7.0
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

![MCP Sync](mcpsync.png)

[![npm version](https://img.shields.io/npm/v/@feli0x/mcps.svg)](https://www.npmjs.com/package/@feli0x/mcps)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@feli0x/mcps.svg)](https://nodejs.org/)

A powerful CLI tool for managing **Model Context Protocol (MCP)** server definitions across multiple AI coding assistants. `mcps` provides a unified interface to configure MCP servers for Cursor, Codex, Gemini, Claude, and other compatible hosts.

## What is MCP?

The Model Context Protocol (MCP) is a standard that enables AI coding assistants to securely connect to external data sources and tools. MCP servers act as bridges between AI assistants and various services, databases, APIs, and file systems.

## Features

- 🚀 **Multi-host support**: Manage MCP servers for Cursor, Codex, Gemini, Claude, and more
- 🔍 **Auto-discovery**: Automatically detect and import existing MCP configurations
- 📦 **Easy installation**: Install MCP servers across multiple hosts with a single command
- 🎯 **Selective management**: Add/remove servers from specific hosts or all at once
- 📋 **Clean organization**: Centralized JSON store with atomic writes and sorted data
- 🛠️ **Developer-friendly**: TypeScript, comprehensive tests, and modern tooling
- 🌐 **Web editor**: Modern React-based editor with Monaco for visual configuration

## Supported Hosts

| Host | Config Location | Status |
|------|----------------|--------|
| **Cursor** | `~/.cursor/mcp.json` | ✅ Supported |
| **Codex** | `~/.codex/config.toml` | ✅ Supported |
| **Gemini** | `~/.gemini/settings.json` | ✅ Supported |
| **Claude** | `~/.claude.json` | ✅ Supported |

## Installation

### Quick Start (recommended)

```bash
npm install -g @feli0x/mcps
```

### Alternative Installation Methods

```bash
# Using pnpm
pnpm add -g @feli0x/mcps

# Using yarn
yarn global add @feli0x/mcps
```

## Usage

### Get Help

```bash
mcps help
```

### Discover Available Hosts

```bash
mcps hosts
```

This command scans your system for supported AI coding assistants and shows their configuration status.

### Run Guided Setup

```bash
mcps setup
```

Walks through host detection and importing existing configurations with confirmations before each step. Use `--yes` to accept all steps automatically or when running in a non-interactive environment.

### Import Existing Configurations

```bash
mcps import
```

Automatically discovers and imports existing MCP server configurations from all supported hosts into the centralized store.

### List Configured Servers

```bash
mcps list
```

Shows all configured MCP servers in a clean table format.

```bash
# Filter by specific hosts
mcps list --cursor --codex

# Output as JSON
mcps list --json
```

### Add or Update a Server

```bash
# Add a new server with command and host bindings
mcps add context7 -- npx -y @upstash/context7-mcp@latest --cursor --codex

# Add hosts to an existing server
mcps add context7 --gemini --claude

# Update command and replace host bindings
mcps add context7 -- npx -y @upstash/context7-mcp@latest --cursor

# Provide environment variables when defining a server
mcps add supabase \
  -- npx -y @supabase/mcp-server-supabase@latest --read-only --project-ref=abc123 \
  -- SUPABASE_ACCESS_TOKEN=12345 OTHER_ENV_VAR="hello world" --codex --gemini
```

You can also use `KEY:VALUE` if your shell makes `KEY=VALUE` quoting awkward (for example, when splitting quoted
segments).

### Remove Servers

```bash
# Remove a server completely
mcps remove context7

# Remove server from specific hosts only
mcps remove context7 --cursor --codex
```

### Install MCP Servers

```bash
mcps install
```

Installs all configured MCP servers to their designated hosts. This writes the server configurations to the appropriate config files for each host.

### Show Version

```bash
mcps version
```

### Web Editor

```bash
mcps editor
```

Launches a web-based editor for managing MCP server configurations. Features:
- Modern React + TypeScript interface
- Monaco editor with JSON schema validation and autocomplete
- Real-time validation and error checking
- Visual onboarding for first-time setup
- Keyboard shortcuts (Ctrl/⌘+S to save)

The web editor runs on `http://localhost:7331` by default.

## Data Storage

`mcps` stores all server definitions in a centralized JSON file at `~/.mcps/mcps.json`. This file contains:

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "hosts": ["cursor", "codex"]
    }
  }
}
```

The tool ensures:
- **Atomic writes**: Uses temporary files and rename operations to prevent corruption
- **Sorted data**: Keys and arrays are always sorted for consistent diffs
- **Validation**: Server names must be lowercase alphanumeric with hyphens only

## Examples

### Complete Workflow

```bash
# 1. Check what hosts are available
mcps hosts

# 2. Import any existing configurations
mcps import

# 3. Add a new MCP server
mcps add filesystem -- npx -y @modelcontextprotocol/server-filesystem@latest --cursor --codex

# 4. List all servers
mcps list

# 5. Install to all configured hosts
mcps install
```

### Managing Multiple Servers

```bash
# Add several servers
mcps add github -- npx -y @modelcontextprotocol/server-github@latest --cursor --codex
mcps add sqlite -- npx -y @modelcontextprotocol/server-sqlite@latest --cursor
mcps add postgres -- npx -y @modelcontextprotocol/server-postgres@latest --codex --gemini

# List servers for specific hosts
mcps list --cursor
mcps list --codex

# Remove a server from one host
mcps remove github --codex

# Remove a server completely
mcps remove sqlite
```

## Development

### Prerequisites

- Node.js 20 or higher
- pnpm 9.0.0

### Setup

```bash
# Clone the repository
git clone https://github.com/feli0x/mcps.git
cd mcps

# Install dependencies
pnpm install

# Build the project
pnpm build
```

### Web Development

For developing the React-based web editor:

```bash
# Start development servers (backend + frontend)
pnpm dev

# Backend only (API server)
pnpm dev:backend

# Frontend only (React app)
pnpm dev:frontend
```

The development setup runs:
- Backend API server on `http://localhost:7331`
- Frontend dev server on `http://localhost:5173` (proxies API calls to backend)

### Available Scripts

```bash
pnpm lint          # Run ESLint (both backend and frontend)
pnpm typecheck     # Run TypeScript type checking (both backend and frontend)
pnpm test          # Run test suite
pnpm build         # Build both backend and frontend
pnpm build:backend # Build only the CLI backend
pnpm build:frontend# Build only the web frontend
pnpm clean         # Remove all build artifacts
pnpm dev           # Start development servers
```

### Running Tests

```bash
# Run all tests
pnpm test

# Run tests in watch mode
pnpm test --watch

# Run tests with coverage
pnpm test --coverage
```

### Project Structure

```
src/
├── cli.ts                    # Main CLI entry point
├── cli/
│   └── hostFlagParser.ts     # Host flag parsing logic
├── core/
│   ├── hosts/               # Host detection and management
│   ├── import/              # Configuration import logic
│   ├── install/             # Installation operations
│   └── servers/             # Server management operations
├── shared/                  # Shared utilities and types
└── web/
    └── editorServer.ts      # Web editor backend server
web/
├── src/
│   ├── components/         # React components (UI, Editor)
│   ├── api/               # API client for backend communication
│   ├── types/             # TypeScript definitions
│   └── lib/               # Utilities and helpers
├── vite.config.ts         # Vite configuration
└── package.json           # Frontend dependencies
```

## Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Development Workflow

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Run tests: `pnpm test && pnpm typecheck && pnpm lint`
5. Commit your changes: `git commit -m 'feat: add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

### Code Style

- Use TypeScript with strict type checking
- Follow the existing ESLint configuration
- Write tests for new functionality
- Use conventional commit messages
- Keep functions small and focused (< 20 lines when possible)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with [Commander.js](https://github.com/tj/commander.js) for CLI functionality
- Uses [Vitest](https://vitest.dev/) for testing
- Inspired by the Model Context Protocol specification

## Support

- 📖 [Documentation](https://github.com/feli0x/mcps#readme)
- 🐛 [Report Issues](https://github.com/feli0x/mcps/issues)
- 💬 [Discussions](https://github.com/feli0x/mcps/discussions)
- 📧 [Contact](mailto:your-email@example.com)

---

**Made with ❤️ for the AI coding community**