mcps - MCP CLI Manager

A powerful command-line tool for managing and calling MCP (Model Context Protocol) servers.

Installation

npm install -g @maplezzk/mcps

Configuration Examples

Adding Various MCP Servers

# Add fetch server (web scraping)
mcps add fetch --command uvx --args mcp-server-fetch

# Add PostgreSQL server
mcps add postgres --command npx --args @modelcontextprotocol/server-postgres --env POSTGRES_CONNECTION_STRING="${DATABASE_URL}"

# Add GitLab server
mcps add gitlab --command npx --args gitlab-mcp-server

# Add SSE server
mcps add remote --type sse --url http://localhost:8000/sse

# Add HTTP server
mcps add http-server --type http --url http://localhost:8000/mcp

Config File Example (~/.mcps/mcp.json)

{
  "servers": [
    {
      "name": "fetch",
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    {
      "name": "postgres",
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    },
    {
      "name": "gitlab",
      "type": "stdio",
      "command": "npx",
      "args": ["gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${GITLAB_TOKEN}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  ]
}

Note: Use environment variables for sensitive data (${VAR_NAME} format).

Quick Start

# 1. Add an MCP server
mcps add fetch --command uvx --args mcp-server-fetch

# 2. Start the daemon
mcps start

# 3. Check status
mcps status

# 4. List available tools
mcps tools fetch

# 5. Call a tool
mcps call fetch fetch url="https://example.com"

Command Reference

Server Management

Command	Description
mcps ls	List all configured servers
mcps add <name> --command <cmd> --args <args>	Add a new server
mcps rm <name>	Remove a server
mcps update [name]	Update server configuration
mcps update <name> --disabled true	Disable a server

Daemon Control

Command	Description
mcps start [--verbose]	Start daemon (verbose mode for debugging)
mcps stop	Stop daemon
mcps restart [server]	Restart daemon or specific server
mcps status	Check daemon status

Tool Invocation

Command	Description
mcps tools <server> [--simple]	List available tools
mcps call <server> <tool> [args...]	Call a tool

Tool Invocation: Parameter Passing

Default Mode (Auto JSON Parsing)

# String values are sent as-is
mcps call fetch fetch url="https://example.com"

# Numbers and booleans are auto-parsed
mcps call fetch fetch max_length=5000 follow_redirects=true
# Sends: { "max_length": 5000, "follow_redirects": true }

# JSON objects (use single quotes outside)
mcps call my-server createUser user='{"name": "Alice", "age": 30}'

--raw Mode (Keep Values as Strings)

# Use --raw for SQL IDs, codes, or strings that should not be parsed
mcps call my-db createOrder --raw order_id="12345" sku="ABC-001"
# Sends: { "order_id": "12345", "sku": "ABC-001" }

# SQL with special characters
mcps call alibaba-dms createDataChangeOrder --raw \
  database_id="123" \
  script="DELETE FROM table WHERE id = 'xxx';" \
  logic="true"

--json Mode (Complex Parameters)

# From JSON string
mcps call my-server createUser --json '{"name": "Alice", "age": 30}'

# From file
mcps call my-server createUser --json params.json

Real-World Usage Examples

Scenario 1: Web Scraping and Search

# Fetch webpage content
mcps call fetch fetch url="https://example.com" max_length=5000

# Deep fetch (follow links)
mcps call fetch fetch url="https://example.com" follow_redirects=true max_depth=2

# Filtered fetch
mcps call fetch fetch url="https://news.example.com" include_tags='["article", "p"]' exclude_tags='["script", "style"]'

Scenario 2: Database Query

# Query data (auto-parsed parameters)
mcps call postgres query sql="SELECT * FROM users WHERE active = true LIMIT 10"

# Keep parameters as strings (use --raw)
mcps call postgres query --raw sql="SELECT * FROM orders WHERE id = '12345'"

Scenario 3: Complex Parameter Passing

# JSON object parameters
mcps call my-server createUser user='{"name": "Alice", "age": 30, "tags": ["admin", "user"]}'

# Load JSON from file
mcps call my-server createUser --json user.json

# Mixed parameters (some auto-parsed, some raw)
mcps call my-server update --raw id="123" data='{"name": "Updated"}'

Scenario 4: Server Management

# View all server configurations
mcps ls

# Check active connections
mcps status

# Restart a single server
mcps restart postgres

# Restart all servers
mcps restart

# Disable a server (without removing config)
mcps update my-server --disabled true

# Remove a server
mcps rm my-server

Scenario 5: Tool Filtering and Search

# Show only tool names (simple mode)
mcps tools postgres --simple

# Filter tools by keyword
mcps tools postgres --tool query --tool describe

# Find tools containing "create"
mcps tools postgres --tool create

Configuration

• Config file: ~/.mcps/mcp.json
• Environment variables:
  • MCPS_CONFIG_DIR: Config directory
  • MCPS_PORT: Daemon port (default: 4100)
  • MCPS_VERBOSE: Verbose logging mode

FAQ

Q: How to check server status?

mcps status  # Check active connections
mcps ls      # Check all configurations (including disabled)

Q: Server connection failed?

mcps start --verbose  # View detailed logs
mcps restart my-server  # Restart specific server

Q: How to quickly find tools?

mcps tools my-server --tool keyword  # Filter by keyword
mcps tools my-server --simple        # Show names only

Q: Special characters in parameters (e.g., SQL)?

# Use --raw to keep string format
mcps call alibaba-dms createDataChangeOrder --raw \
  database_id="123" \
  script="DELETE FROM table WHERE id = 'xxx';" \
  logic="true"

Q: Daemon starts slowly?

• First start loads all servers, 10-15 seconds is normal
• Subsequent starts are faster (~2 seconds)
• Use mcps ls to check config without starting daemon