klysdale/alpaca-mcp-server

Alpaca MCP Server (Docker)

Containerized deployment of the official alpaca-mcp-server configured for HTTP-based MCP transport with credentials baked into the image. This repository targets scenarios where a single Alpaca account powers downstream services (such as a chatbot API) without requiring callers to provide API keys on each request.

Features

• Python-based MCP server using alpaca-mcp-server serve --transport http by default
• Docker image exposes the server on port 7800 (configurable) with JSON-RPC served at /mcp
• Build-time credential injection via ARG -> ENV, with runtime validation
• Example docker-compose.yml showing how to run alongside a chatbot service
• Simple TCP health check to confirm the MCP listener is up

Repository Layout

.
|-- Dockerfile
|-- docker-compose.yml
|-- entrypoint.sh
`-- scripts/
    `-- healthcheck.py

Requirements

• Docker 24+
• Docker Compose v2 (optional, for multi-service setups)

Build-Time Configuration

Important: The entrypoint refuses to start if ALPACA_API_KEY or ALPACA_SECRET_KEY remains changeme or empty.

Build with baked credentials

docker build \
  --build-arg ALPACA_API_KEY="your-key" \
  --build-arg ALPACA_SECRET_KEY="your-secret" \
  --build-arg ALPACA_API_BASE_URL="https://paper-api.alpaca.markets" \
  -t alpaca-mcp-server:local .

Credentials provided via build arguments are copied into environment variables inside the image. Because the values live in the final image, avoid pushing the resulting image to public registries.

Running the Container

docker run --rm \
  -p 7800:7800 \
  alpaca-mcp-server:local

Environment overrides at runtime are optional but supported. For example, to change the exposed port without rebuilding:

docker run --rm \
  -e PORT=9000 \
  -p 9000:9000 \
  alpaca-mcp-server:local

To switch transports (e.g., to server-sent events), set MCP_TRANSPORT:

docker run --rm \
  -e MCP_TRANSPORT=sse \
  -p 7800:7800 \
  alpaca-mcp-server:local

Docker Compose Example

The included docker-compose.yml builds the image with your credentials and runs the server as a managed service.

1. Create an .env file alongside docker-compose.yml:

   ALPACA_API_KEY=your-key
   ALPACA_SECRET_KEY=your-secret
   # Optional overrides
   # ALPACA_API_BASE_URL=https://api.alpaca.markets
   # PORT=7800
   # MCP_TRANSPORT=http
   

2. Build and launch the MCP server:

   docker compose up --build
   

   The server listens on http://localhost:${PORT:-7800}/mcp for clients connecting from the host machine.

Health & Diagnostics

• The image defines a Docker HEALTHCHECK that opens a TCP connection to the configured port.

• View container logs for startup confirmation:

  docker logs <container-name>
  

  Example log line: Starting Alpaca MCP server on 0.0.0.0:7800 (transport=http)

• To manually verify connectivity from the host:

  curl -X POST http://localhost:7800/mcp \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0","capabilities":{}}}'
  
  

• When testing with Postman or curl, include both Accept: application/json and Accept: text/event-stream to satisfy the Streamable HTTP requirements. Without these headers the server returns Not Acceptable.

Security Notes

• Keep the repository free of real API credentials. Pass secrets via CLI flags, .env files excluded from version control, or a secure secrets manager.
• Treat any built image as sensitive material. Anyone with the image can extract the baked-in keys.
• Logging intentionally omits credential material; avoid adding verbose/debug logs that could leak secrets.

Updating Dependencies

To update alpaca-mcp-server inside the image, rebuild with the latest tag pulled from PyPI:

docker build --pull --no-cache -t alpaca-mcp-server:local .

License

This project is provided as-is. Refer to Alpaca's terms of service for usage restrictions tied to your API credentials.