Cross-Repository MCP Server Setup System

A comprehensive system for managing Model Context Protocol (MCP) servers across multiple repositories and environments.

Overview

This system provides:

• Global Installation: Install MCP servers once and use them across all repositories
• Per-Repository Configuration: Override global settings on a per-repository basis
• Unified CLI: Manage all MCP servers with a single command-line tool
• Cross-Platform Support: Works on Linux, macOS, and Windows
• Version Management: Update and manage server versions easily
• Configuration Inheritance: Smart configuration merging with clear priority rules

Architecture

Cross-Repository MCP Setup System
├── global-mcp-setup/          # Global installation and configuration
│   ├── install.sh             # Unix/Linux/macOS installer
│   ├── install.ps1            # Windows PowerShell installer
│   └── config/
│       ├── claude_desktop_config.json      # Global Claude Desktop config template
│       └── global-mcp-registry.json        # Registry of all available servers
│
├── per-repo-setup/            # Per-repository initialization
│   ├── setup-mcp.sh           # Repository initialization script
│   └── .mcp/                  # Template configuration
│       ├── config.json        # Repository configuration template
│       └── servers.json       # Server definitions template
│
└── mcp-cli/                   # Command-line management tool
    ├── src/
    │   ├── cli.ts             # Main CLI entry point
    │   ├── commands/          # Command implementations
    │   └── utils/             # Utility functions
    └── package.json

Quick Start

1. Global Installation

Install MCP servers globally on your system:

Unix/Linux/macOS:

cd global-mcp-setup
./install.sh

Windows:

cd global-mcp-setup
.\install.ps1

This will:

• Create ~/.mcp directory structure
• Install the global MCP server registry
• Configure Claude Desktop
• Install core MCP servers

2. Install the CLI Tool

cd mcp-cli
npm install
npm run build
npm link

Now the mcp command is available globally.

3. Initialize a Repository

In any repository where you want to use MCP:

cd /path/to/your/repository
mcp init

This creates a .mcp/ directory with repository-specific configuration.

4. Enable Servers

Enable servers for your repository:

# Enable servers for this repository
mcp enable filesystem git

# Enable a server globally
mcp enable github --global

5. Configure Secrets

Edit .mcp/local.json to add environment variables and secrets:

{
  "servers": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

Directory Structure

Global MCP Home (~/.mcp)

~/.mcp/
├── servers/                   # Installed servers
│   ├── filesystem/
│   ├── git/
│   ├── github/
│   └── ...
├── configs/                   # Global configurations
├── logs/                      # Server logs
└── global-mcp-registry.json   # Server registry

Repository MCP Config (.mcp)

.mcp/
├── config.json               # Main repository configuration
├── servers.json              # Server definitions and overrides
├── local.json                # Local overrides (gitignored)
├── secrets.json              # Secret values (gitignored)
└── README.md                 # Configuration documentation

Configuration System

Configuration Priority

Configuration is merged in this order (later overrides earlier):

1. Global Configuration (~/.mcp/ and Claude Desktop config)
2. Repository Configuration (.mcp/servers.json)
3. Local Configuration (.mcp/local.json)
4. Environment Variables

Example Configuration Flow

Global Config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": ["/Users/name/.mcp/servers/filesystem/dist/index.js"],
      "enabled": true
    }
  }
}

Repository Config (.mcp/servers.json):

{
  "servers": {
    "filesystem": {
      "enabled": true,
      "env": {
        "ALLOWED_DIRECTORIES": "${REPO_ROOT}/src"
      },
      "inheritGlobal": true
    },
    "github": {
      "enabled": true,
      "env": {
        "GITHUB_REPOSITORY": "owner/repo"
      }
    }
  }
}

Local Config (.mcp/local.json):

{
  "servers": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Available Servers

The system includes these MCP servers in the global registry:

Core Servers

• filesystem - Access and manipulate local files and directories
• git - Interact with Git repositories

API Integrations

• github - GitHub repositories, issues, and pull requests
• slack - Send and read messages in Slack
• google-drive - Access and manage Google Drive files

Databases

• postgres - Query and manage PostgreSQL databases
• sqlite - Query and manage SQLite databases

Utilities

• brave-search - Search the web using Brave Search API
• memory - Persistent memory and context storage
• puppeteer - Browser automation and web scraping

CLI Commands

Installation & Setup

mcp install <server>        # Install a server
mcp init                    # Initialize MCP in current repository

Server Management

mcp list                    # List all servers
mcp enable <server>         # Enable a server
mcp disable <server>        # Disable a server
mcp update [server]         # Update servers

Information

mcp status                  # Show status of MCP installation
mcp info <server>           # Show detailed server information
mcp search <query>          # Search for servers

Configuration

mcp config --show           # Show current configuration
mcp config --edit           # Edit configuration

See mcp-cli/README.md for complete CLI documentation.

Use Cases

Scenario 1: Individual Developer

Setup:

1. Run global installation once
2. Install CLI tool
3. In each project, run mcp init
4. Enable needed servers per project

Benefits:

• Servers installed once, used everywhere
• Per-project configuration
• Easy to manage secrets locally

Scenario 2: Team Environment

Setup:

1. Each team member runs global installation
2. Repository .mcp/servers.json is committed to git
3. Secrets in .mcp/local.json (gitignored)
4. Team members share same server configuration

Benefits:

• Consistent server setup across team
• Environment-specific secrets
• Easy onboarding for new team members

Scenario 3: CI/CD Pipeline

Setup:

1. Install MCP in CI environment
2. Use environment variables for configuration
3. Enable only required servers for CI tasks

Benefits:

• Automated testing with MCP servers
• Secure secret management
• Consistent with local development

Advanced Features

Custom Server Registry

Add custom servers to the global registry:

# Edit the registry
vim ~/.mcp/global-mcp-registry.json

# Add your server:
{
  "servers": [
    {
      "name": "my-custom-server",
      "displayName": "My Custom Server",
      "description": "Custom MCP server for my needs",
      "repository": "https://github.com/me/my-mcp-server",
      "installType": "git",
      "defaultEnabled": false,
      "requiresConfig": false
    }
  ]
}

# Install it
mcp install my-custom-server --global

Environment Variable Expansion

All configuration files support environment variable expansion:

{
  "servers": {
    "postgres": {
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}",
        "REPO_ROOT": "${REPO_ROOT}"
      }
    }
  }
}

Variables are resolved in this order:

1. Local context variables (REPO_ROOT, MCP_HOME, etc.)
2. Environment variables
3. Original value if not found

Scoped Servers

Servers can have different scopes:

• global - Available to all repositories
• repository - Scoped to repository directory
• project - Shared across related repositories

Example:

{
  "servers": {
    "filesystem": {
      "scope": "repository",
      "env": {
        "ALLOWED_DIRECTORIES": "${REPO_ROOT}"
      }
    },
    "slack": {
      "scope": "global"
    }
  }
}

Security Best Practices

1. Never commit secrets

   • Always use .mcp/local.json for sensitive data
   • Verify .gitignore includes .mcp/local.json and .mcp/secrets.json

2. Use environment variables

   • Reference secrets via ${VAR_NAME} syntax
   • Keep actual values in environment or local config

3. Restrict file access

   • Use ALLOWED_DIRECTORIES for filesystem server
   • Limit server permissions to minimum required

4. Regular updates

   • Run mcp update --all regularly
   • Check for security advisories

Troubleshooting

MCP servers not appearing in Claude Desktop

1. Check configuration:

   mcp status --verbose
   

2. Verify Claude Desktop config location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

3. Restart Claude Desktop

Server installation fails

1. Check dependencies:

   node --version  # Should be 16+
   npm --version
   git --version
   

2. Check network connectivity

3. Try force reinstall:

   mcp install <server> --force
   

Configuration not taking effect

Check configuration priority:

# Show merged configuration
mcp config --show

# Check repository config
cat .mcp/servers.json

# Check local overrides
cat .mcp/local.json

Platform-Specific Notes

macOS

• Claude Desktop config in ~/Library/Application Support/Claude/
• May need to allow terminal access in Security & Privacy settings

Windows

• Use PowerShell for installation
• Claude Desktop config in %APPDATA%\Claude\
• Path separators automatically handled

Linux

• Claude Desktop config in ~/.config/Claude/
• May need to install Node.js via package manager

Migration Guide

From Manual MCP Setup

If you have existing MCP servers configured manually:

1. Backup your current config:

   cp ~/Library/Application\ Support/Claude/claude_desktop_config.json ~/Desktop/backup.json
   

2. Run global installation:

   cd global-mcp-setup && ./install.sh
   

3. Migrate your servers:

   • The installer backs up existing config automatically
   • Review ~/.mcp/global-mcp-registry.json
   • Enable servers: mcp enable <server> --global

4. Initialize repositories:

   cd /path/to/repo && mcp init
   

Contributing

Contributions welcome! Areas for improvement:

• Additional MCP servers in registry
• Windows-specific enhancements
• CI/CD integration examples
• Documentation improvements
• Test coverage

License

MIT

Support

• Report issues on GitHub
• Check documentation in each subdirectory
• Review server-specific README files

Changelog

Version 1.0.0

• Initial release
• Global and per-repository setup
• CLI tool for management
• Cross-platform support
• Configuration inheritance system
• Server registry with 10 core servers