Installation

Installation

Prerequisites

• Python 3.11+
• Node.js 18+
• PostgreSQL 15+ (or SQLite for development)

Quick Start

1. Clone the Repository

git clone https://github.com/RunTimeAdmin/MCPShield.git
cd MCPShield

2. Start the Backend

cd backend
python -m venv venv
source venv/bin/activate  # On Windows: .\venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Backend runs on http://localhost:8000

3. Start the Frontend

cd frontend
npm install
npm run dev

Frontend runs on http://localhost:3000

4. Install the Agent

cd agent
pip install -e .
mcpshield --version

Docker Deployment

1. Set Required Environment Variables

# Generate JWT secret (required - backend will not start without it)
# Bash / macOS / Linux:
export JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")

# PowerShell (Windows):
# $env:JWT_SECRET = python -c "import secrets; print(secrets.token_hex(32))"

2. Start Services

docker-compose up -d

This starts:

• PostgreSQL database on port 5432
• FastAPI backend on port 8000
• Next.js frontend on port 3000

Environment Variables

Backend (.env)

Variable	Default	Description
DATABASE_URL	sqlite:///./mcpshield.db	Database connection string
JWT_SECRET	Required - generate with python -c "import secrets; print(secrets.token_hex(32))"	JWT signing key
ACCESS_TOKEN_EXPIRE_MINUTES	30	JWT expiration
ALLOWED_ORIGINS	http://localhost:3000	CORS origins

Frontend (.env.local)

Variable	Default	Description
NEXT_PUBLIC_API_URL	http://localhost:8000	Backend API URL

Next Steps

1. Open http://localhost:3000
2. Register a new account
3. Create an agent and copy the API key
4. Configure the agent: mcpshield configure --api-key YOUR_KEY
5. Run a scan: mcpshield scan