MCP Servers

This repository contains configuration and setup for various Model Context Protocol (MCP) servers to use with Claude Desktop and other AI assistants.

Introduction

This project was created to streamline the setup and management of MCP servers for use with Claude products. I primarily use this setup with Claude Desktop and Claude Code on Mac OS X, and I'm planning to integrate it with Cursor in the future.

If you're using Windows, you can use this as a general guide, but you'll want to adjust paths and commands accordingly.

This configuration was developed with the help of Claude through Cursor's agent view and web search to ensure we follow best practices. It's designed to be secure, flexible, and easy to maintain.

MCP Organization Best Practices

Directory Structure

We follow these conventions for organizing MCP-related files:

~/mcp/                         # Main MCP projects directory
├── .venv/                     # Python virtual environment for project-specific MCP servers
├── claude_desktop_config.json # Reference config file
├── README.md                  # This documentation
├── install-config.sh          # Installation script
├── setup-mcp-secrets.sh       # Secrets setup script
└── uv_notes.md                # Notes on using uv for Python dependencies

Virtual Environment Management

For Python-based MCP servers, we follow these conventions:

1. Project-specific MCP servers:

- Create a project-local virtual environment in the project directory
- Install MCP servers within this environment using uv
- Example: cd ~/mcp && uv venv && source .venv/bin/activate

2. Global MCP servers:
- Install using uv tool install <server-name>
- These are available at ~/.local/bin/

Dependency Management

Always use uv for Python package management:

- Tool installation: uv tool install <tool-name>
- Virtual env creation: uv venv
- Package installation: uv pip install <package-name>

Installed MCP Servers

The following MCP servers have been installed and configured:

1. Filesystem - Access files and directories on your local filesystem

- Installed via: npm install -g @modelcontextprotocol/server-filesystem
- Configure with paths to directories you want to access

2. SQLite - Query SQLite databases

- Installed via: uv tool install mcp-server-sqlite
- Configure with paths to your database files

SQLite Database Registry:

To add multiple project databases, update the SQLite configuration in claude_desktop_config.json:

   "sqlite": {
     "command": "path/to/mcp-server-sqlite",
     "args": [
       "--db-path",
       "path/to/your/database.db"
     ],
     "env": {
       "MCP_SQLITE_REGISTRY": "path/to/db1.sqlite:path/to/db2.db:path/to/db3.sqlite"
     }
   }
   

Then access these databases in Claude by specifying the full path:

   -- Query first database
   SELECT  FROM users WHERE id = 1 -- Using path/to/db1.sqlite
-- Switch to second database

   USE DATABASE path/to/db2.db;

   SELECT  FROM products;

   

Important: Always restart Claude Desktop after making changes to the configuration file.

3. Puppeteer - Web browsing and automation

- Installed via: npm install -g @modelcontextprotocol/server-puppeteer
- Configured to use local Chrome installation
- Environment variables:
- PUPPETEER_HEADLESS: Set to "true" for headless operation
- PUPPETEER_EXECUTABLE_PATH: Points to local Chrome installation
- Note: We use the Node.js implementation for better local network access and no Docker dependency

4. GitHub - Access GitHub repositories and issues

- Installed via: npm install -g @modelcontextprotocol/server-github
- Requires environment variable: GITHUB_PERSONAL_ACCESS_TOKEN

5. Time - Get current time and date information

- Installed via: uv tool install mcp-server-time
- Configure with your local timezone

6. Fetch - Make HTTP requests and parse web content

- Installed via: uv tool install mcp-server-fetch
- Enhanced with dual configuration for better HTTP request handling
- Added environment variables to nudge Claude to prefer fetch for HTTP requests

7. CLI - Execute commands securely
- Installed in project virtual environment: cd ~/mcp && source .venv/bin/activate && uv pip install cli-mcp-server
- Configured for HTTP operations with appropriate permissions

Configuration

The Claude Desktop configuration file is located at:

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: C:\Users\USERNAME\AppData\Roaming\Claude\claude_desktop_config.json

Setting Up Your Configuration

This repository includes two configuration files:

- claude_desktop_config.template.json - A template with placeholders for paths and settings
- Your actual configuration file (excluded from git by default)

To set up your configuration:

1. Create a custom configuration file:

cp claude_desktop_config.template.json claude_desktop_config.custom.json

2. Edit your custom configuration file to include your specific paths and settings:

```bash