Mcpd

After download: make the file executable on macOS/Linux (chmod +x mcpd-...).

Quick Start

Using Docker

# Create a directory for your scripts
mkdir -p scripts

# Create a date example script with description and options
cat > scripts/date &2
  exit 0
fi

# Use format from environment variable if provided
if [ -n "$format" ]; then
  date "$format"
else
  date
fi
EOF
chmod +x scripts/date

# Run mcpd with Docker
docker run --rm -it -p 1995:1995 -v "$(pwd)/scripts:/var/lib/mcpd" ghcr.io/pouriya/mcpd:latest

Open your browser to http://localhost:1995 to access the web dashboard and test your tools.

Using with AI Assistants

Once mcpd is running, configure your AI assistant to connect to it.

Cursor

Add to your .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "mcpd": {
      "url": "http://localhost:1995/api/mcp"
    }
  }
}

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mcpd": {
      "url": "http://localhost:1995/api/mcp"
    }
  }
}

OpenAI Codex CLI

Add to your ~/.codex/config.json:

{
  "mcpServers": {
    "mcpd": {
      "url": "http://localhost:1995/api/mcp"
    }
  }
}

Any MCP Client

Point your MCP client to the endpoint:

http://localhost:1995/api/mcp

Configuration

Click to expand all configuration options

HTTP Server Options

| Option | Env Variable | Default | Description | |-------|--------------|---------|-------------| | --http-host | MCPD_HTTP_HOST | 127.0.0.1 | HTTP server listen address | | --http-port | MCPD_HTTP_PORT | 1995 | HTTP server listen port number | | --http-base-path | MCPD_HTTP_BASE_PATH | / | HTTP server base path (currently not used) | | --http-tls-cert-file | MCPD_HTTP_TLS_CERT_FILE | - | TLS certificate file (enables HTTPS when used with --http-tls-key-file) | | --http-tls-key-file | MCPD_HTTP_TLS_KEY_FILE | - | TLS private key file (enables HTTPS when used with --http-tls-cert-file) | | --http-read-timeout-secs | MCPD_HTTP_READ_TIMEOUT | 5 | Read timeout for client connections in seconds | | --http-write-timeout-secs | MCPD_HTTP_WRITE_TIMEOUT | 5 | Write timeout for client connections in seconds |

HTTP Authentication Options

| Option | Env Variable | Default | Description | |-------|--------------|---------|-------------| | --http-auth-username | MCPD_HTTP_AUTH_USERNAME | ` | Authentication username (defaults to admin if password is set) | | --http-auth-password-file | MCPDHTTPAUTHPASSWORDFILE | - | A file containing bcrypt(password: sha256(plain_password) of your user password | | --http-auth-password-sha256-bcrypt | MCPDHTTPAUTHPASSWORDSHA256BCRYPT | - | A file containing bcrypt(password: sha256(plain_password) of your user password | | --http-auth-captcha | MCPDHTTPAUTHCAPTCHA | false | Enable CAPTCHA for authentication | | --http-auth-captcha-case-sensitive | MCPDHTTPAUTHCAPTCHACASESENSITIVE | false | Make CAPTCHA case-sensitive | | --http-auth-api-token | MCPDHTTPAUTHAPITOKEN | - | Hardcoded bearer token that never expires | | --http-auth-token-timeout | MCPDHTTPAUTHTOKEN_TIMEOUT | 604800` | Timeout for dynamically generated tokens in seconds (default: 1 week) |

Script Options

| Option | Env Variable | Default | Description | |-------|--------------|---------|-------------| | --script-root-directory | MCPD_SCRIPT_ROOT_DIRECTORY | Required | Root directory containing executable scripts (must exist) | | --script-config | - | - | Configuration key/value pairs for scripts in KEY=VALUE format (JSON values, can be specified multiple times) |

Web Dashboard Options

| Option | Env Variable | Default | Description | |-------|--------------|---------|-------------| | --www-ui-disable | MCPD_WWW_UI_DISABLE | false | Disable the web dashboard | | --www-config | - | - | Configuration key/value pairs for web dashboard in KEY=VALUE format (accessible via /api/public/configuration) |

Logging Options

| Option | Env Variable | Default | Description | |-------|--------------|---------|-------------| | --trace | - | false | Enable trace level logging (shows target and location) | | --debug | - | false | Enable debug level logging (shows target) | | --quiet | - | false | Disable all logging |

Use --help to see detailed descriptions of all options.

MCP Endpoint

POST /api/mcp
Content-Type: application/json

Supported methods: initialize, tools/list, tools/call, resources/list, resources/read

The server supports JSON-RPC 2.0 batch requests and notifications.

Writing Scripts

See [SCRIPT.md](SCRIPT.md) for the complete specification.

Examples

Learn how to write scripts by exploring the sample implementations:

• Basic examples — hello-world, greet, echo
• Intermediate examples — calculator, validation, system info
• Advanced examples — stateful counter, key-value store, task queue

Additional HTTP Endpoints

Besides the MCP endpoint, mcpd provides:

• GET /api/public/captcha - Get CAPTCHA image (if enabled)
• GET /api/public/configuration - Get public configuration
• GET /api/auth/test - Test authentication
• POST /api/auth/token - Get authentication token
• POST /api/setPassword - Change password (requires password file)

License

BSD-3-Clause

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pouriya
• Source: pouriya/mcpd
• License: BSD-3-Clause

Install and usage instructions live in the source repository linked above.