MCP-Forge Quick Start Guide

Installation

# Install from source
git clone <repository>
cd mcp-forge
uv sync

Configuration

Copy the example configuration:

cp config.example.yaml config.yaml

Edit config.yaml to set your Podman socket path:

server:
  podman_socket: /run/user/1000/podman/podman.sock  # Update this

Ensure Podman is running:

systemctl --user start podman.socket

Running the Server

stdio Transport (default)

mcp-forge --config config.yaml

SSE Transport (HTTP)

mcp-forge --config config.yaml --transport sse --host 0.0.0.0 --port 8080

Command-Line Options

--config PATH        Path to configuration file (required)
--host HOST          Server host address (default: localhost)
--port PORT          Server port (default: 3000)
--transport TYPE     Transport protocol: stdio or sse (default: stdio)
--verbose, -v        Enable verbose logging

MCP Client Configuration

To use with an MCP client (e.g., Claude Desktop), add to your client config:

{
  "mcpServers": {
    "mcp-forge": {
      "command": "mcp-forge",
      "args": ["--config", "/path/to/config.yaml"]
    }
  }
}

Testing

Run the test suite:

uv run pytest

Run specific tests:

uv run pytest tests/server/test_server_integration.py -v

Architecture

Simple Backend: Stateless Python execution in fresh containers
Jupyter Backend: Stateful sessions with kernel persistence
Security: Resource limits, package validation, audit logging
MCP Integration: Bridge to external MCP tool servers

Troubleshooting

Podman Socket Not Found

Ensure Podman socket is running:

systemctl --user status podman.socket
systemctl --user start podman.socket

Permission Denied

Check socket permissions:

ls -l /run/user/$(id -u)/podman/podman.sock

Container Images

Build or pull required images:

podman pull python:3.11-slim
podman tag python:3.11-slim mcp-forge/python:3.11

2 KiB Raw Blame History