AGENTS.md

How to Add a New MCP Server to Claude Desktop

Follow these steps to add a new MCP server that requires environment variables.

Step 1: Add required env vars to .env and .env.sample

Add any environment variables the server needs to .env with their real values (this file is gitignored). Add the same keys with empty values to .env.sample so others know what to configure:

# .env.sample
MY_SERVER_API_KEY=
MY_SERVER_REGION=

Note: mcp.env is sourced with set -a, which exports all variables to the MCP server process. Keep it strictly for MCP-specific secrets and configuration — avoid setting variables like PATH or HOME that could shadow system defaults.

Step 2: Create claude-desktop/scripts/<server-name>.sh

Create a wrapper script that sources the env file before launching the server:

#!/usr/bin/env bash
set -euo pipefail

ENV_FILE="$HOME/.claude/mcp.env"

if [[ ! -f "$ENV_FILE" ]]; then
  echo "ERROR: $ENV_FILE not found. See README for setup instructions." >&2
  exit 1
fi

env_perms=$(stat -Lf "%OLp" "$ENV_FILE")
if [[ "$env_perms" != "600" && "$env_perms" != "400" ]]; then
  echo "ERROR: $ENV_FILE has unsafe permissions ($env_perms). Run: chmod 600 $ENV_FILE" >&2
  exit 1
fi

set -a
source "$ENV_FILE"
set +a

VERSIONS_FILE="$HOME/.claude/mcp-versions.env"
if [[ -f "$VERSIONS_FILE" ]]; then
  source "$VERSIONS_FILE"
fi

exec uvx <server-package-name> "$@"

Replace <server-package-name> with the actual uvx package name (e.g. my-mcp-server@1.2.3). If the server has a version pin, add it to claude-desktop/mcp-versions.env and reference it here as ${MY_SERVER_VERSION}.

Note: If a server does not require a version pin (e.g. it always resolves to latest), do not add a version variable. Document this explicitly in claude-desktop/mcp-versions.env with a comment explaining why it is intentionally unpinned.

Step 3: Add the server entry to claude-desktop/claude_desktop_config.json

Add a new entry under mcpServers with command pointing to your wrapper script. Do not include an env block — all env vars are handled by the wrapper script:

"my-server": {
  "command": "/bin/bash",
  "args": ["-c", "~/.claude/scripts/<server-name>.sh"]
}

Step 4: Make the script executable and secure the env file

chmod +x claude-desktop/scripts/<server-name>.sh
chmod 600 ~/.claude/mcp.env

Step 5: On a new machine, ensure the scripts dir is symlinked

ln -sfn $REPO_DIRECTORY_PATH/claude-desktop/scripts ~/.claude/scripts

Step 6: Restart Claude Desktop

Quit and reopen Claude Desktop for the new MCP server configuration to take effect.

Step 7: Verify the server is running

Open Claude Desktop → Settings → Developer → MCP Servers. The new server should appear with a green status indicator. If it shows red/error, check Console.app for crash logs from the wrapper script.