Skip to main content

​
Installation

LeanMCP is a modular TypeScript SDK for building Model Context Protocol servers. This guide covers installation for all package managers and system requirements.

​
System Requirements

Node.js

Node.js 20.x or higher required

TypeScript

TypeScript 5.0+ recommended for best experience

Package Manager

npm, yarn, or pnpm supported

Operating System

Windows, macOS, or Linux
LeanMCP uses TypeScript decorators and reflect-metadata. Make sure your tsconfig.json has experimentalDecorators and emitDecoratorMetadata enabled.

​
Quick Installation

The fastest way to get started is using the LeanMCP CLI to scaffold a new project: 
npx @leanmcp/cli create my-mcp-server
cd my-mcp-server
npm install
This creates a complete project with all dependencies configured.

​
Package Overview

LeanMCP is split into modular packages. Install only what you need:

​
Core Packages (Required)

Version: 0.4.7The core package provides MCP server runtime, decorators, and schema validation.
npm install @leanmcp/core
Includes:
  • @Tool, @Prompt, @Resource decorators
  • @SchemaConstraint, @Optional schema decorators
  • createHTTPServer() and MCPServer classes
  • Auto-discovery of services
  • Built-in validation with AJV
Dependencies:
  • @modelcontextprotocol/sdk - Official MCP SDK
  • reflect-metadata - Decorator metadata support
  • ajv - JSON Schema validation
  • dotenv - Environment variables
Version: 0.5.12CLI tool for scaffolding projects, adding services, and deployment.
npm install -g @leanmcp/cli
# or as dev dependency
npm install --save-dev @leanmcp/cli
Commands:
  • leanmcp create <name> - Create new project
  • leanmcp add <service> - Add new service
  • leanmcp deploy - Deploy to production
Note: You can also use npx @leanmcp/cli without global installation.

​
Optional Packages

Authentication and access control for MCP servers.
npm install @leanmcp/auth
Use when:
  • You need user authentication
  • Multi-user MCP servers
  • Permission-based access control
Supports:
  • AWS Cognito
  • Auth0
  • Clerk
  • Custom JWT providers
Structured user input during tool execution.
npm install @leanmcp/elicitation
Use when:
  • Tools need guided user input
  • Multi-step workflows
  • Interactive forms during execution
Request-scoped environment and secret injection.
npm install @leanmcp/env-injection
Use when:
  • Multi-tenant secrets management
  • Per-request configuration
  • Dynamic environment variables
UI components for building MCP Apps (advanced).
npm install @leanmcp/ui
Use when:
  • Building interactive MCP experiences
  • Custom UI components for tools

​
Manual Setup

If you prefer to set up a project manually without the CLI:
1

Initialize project

Create a new directory and initialize npm:
mkdir my-mcp-server
cd my-mcp-server
npm init -y
2

Install dependencies

Install LeanMCP core and required dependencies:
npm install @leanmcp/core express cors
npm install --save-dev @types/express @types/cors @types/node typescript tsx
3

Configure TypeScript

Create tsconfig.json with decorator support:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "lib": ["ES2022"],
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "resolveJsonModule": true,
    "outDir": "./dist",
    "rootDir": "./"
  },
  "include": ["**/*.ts"],
  "exclude": ["node_modules", "dist"]
}
The experimentalDecorators and emitDecoratorMetadata options are required for LeanMCP decorators to work.
4

Create main entry point

Create main.ts:
main.ts
import { createHTTPServer } from "@leanmcp/core";

await createHTTPServer({
  name: "my-mcp-server",
  version: "1.0.0",
  port: 8080,
  cors: true,
  logging: true
});
5

Add run scripts

Update package.json:
package.json
{
  "type": "module",
  "scripts": {
    "start": "tsx main.ts",
    "build": "tsc",
    "dev": "tsx watch main.ts"
  }
}

​
Verify Installation

Verify your installation is working:
1

Check Node.js version

node --version
# Should be v20.0.0 or higher
2

Check LeanMCP CLI

npx @leanmcp/cli --version
# Should output version 0.5.12 or higher
3

Run the server

npm start
You should see:
🚀 MCP HTTP Server running on http://localhost:8080
📡 MCP Endpoint: http://localhost:8080/mcp
🏥 Health Check: http://localhost:8080/health
4

Test health endpoint

curl http://localhost:8080/health
Expected response:
{"status":"ok"}

​
Environment Configuration

Create a .env file for environment variables:
.env
# Server Configuration
PORT=8080
NODE_ENV=development

# Optional: Authentication (if using @leanmcp/auth)
# AWS_REGION=us-east-1
# COGNITO_USER_POOL_ID=your-pool-id
# COGNITO_CLIENT_ID=your-client-id

# Optional: Observability
# LEANMCP_API_KEY=your-api-key

​
Troubleshooting

If you see errors about decorators:Error: Experimental support for decorators is a feature that is subject to changeSolution: Ensure your tsconfig.json has:
{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}
If you see errors about module imports:Error: Cannot find module '@leanmcp/core'Solutions:
  1. Ensure package.json has "type": "module"
  2. Check that dependencies are installed: npm install
  3. Clear node_modules and reinstall: rm -rf node_modules package-lock.json && npm install
If port 8080 is already in use:Error: EADDRINUSE: address already in useSolutions:
  1. Change the port in main.ts: port: 3000
  2. Or set PORT environment variable: PORT=3000 npm start
  3. Or kill the process using the port: lsof -ti:8080 | xargs kill

​
Next Steps

Quick Start

Create your first MCP server

Core Concepts

Learn about Tools, Prompts, and Resources

API Reference

Explore the complete API

Examples

See example implementations
Need help? Join our Discord community or open an issue on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us