Installation

Installation

This guide covers all installation options for Workflow MCP.

Package Options

Package	Use Case	Install Command
@blackmesa/workflow-mcp-stdio	Local CLI usage	npm install -g @blackmesa/workflow-mcp-stdio
@blackmesa/workflow-mcp-http	Remote deployment	npm install @blackmesa/workflow-mcp-http
@blackmesa/workflow-mcp-core	Custom integration	npm install @blackmesa/workflow-mcp-core

Local Installation (stdio)

For use with Claude Desktop or other local MCP clients.

1. Install the package

   npm install -g @blackmesa/workflow-mcp-stdio

2. Configure your MCP client

   Add to your .mcp.json file:

   {
     "mcpServers": {
       "workflow": {
         "command": "npx",
         "args": ["@blackmesa/workflow-mcp-stdio"],
         "cwd": "/path/to/your/project"
       }
     }
   }

   Tip

   Set cwd to your project root so session files are created relative to your project.

3. Verify installation

   Restart your MCP client. You should see “workflow” in the available tools.

Remote Installation (HTTP)

For deployment to Render, Fly.io, or your own server.

npm

npm install @blackmesa/workflow-mcp-http

# Start the server
MCP_PORT=3000 npx @blackmesa/workflow-mcp-http

Docker

docker run -p 3000:3000 \
  -e MCP_WORKSPACE_DIR=/data \
  -v ./workflow-data:/data \
  blackmesa/workflow-mcp

Hosted

Use the hosted service at api.workflow-mcp.blackmesa.live:

https://api.workflow-mcp.blackmesa.live/mcp

No deployment required - just configure your MCP client to use this endpoint.

Environment Variables

Variable	Default	Description
MCP_PORT	3000	HTTP server port
MCP_HOST	0.0.0.0	HTTP server host
MCP_BASE_PATH	/mcp	MCP endpoint path
MCP_WORKSPACE_DIR	process.cwd()	Working directory for session files
MCP_OAUTH_ENABLED	false	Enable GitHub OAuth
GITHUB_CLIENT_ID	-	GitHub OAuth client ID
GITHUB_CLIENT_SECRET	-	GitHub OAuth client secret
CORS_ORIGINS	*	Allowed CORS origins (comma-separated)

Next Steps

• Quick Start - Start your first workflow
• Local Deployment - stdio configuration details
• Remote Deployment - HTTP server setup