🎯 What is MCP Forge?

MCP Forge is a powerful scaffolding CLI that generates fully-featured Model Context Protocol (MCP) servers with best practices built-in. Stop writing boilerplate and start building amazing AI integrations!

# Install
pip install mcp-forge

# Create a server
mcp-forge new my-awesome-server

# That's it! 🎉

Your server is ready with tools, resources, prompts, authentication, elicitation, sampling, and more!

✨ Features

🚀 Quick Start

Installation

# Using pip
pip install mcp-forge

# Using uv (recommended for generated projects)
uv tool install mcp-forge

Create Your First Server

# Interactive mode (recommended)
mcp-forge new my-server

# With options
mcp-forge new my-server \
  --description "My awesome MCP server" \
  --with-prompts \
  --with-sampling \
  --with-elicitation

Run It!

cd my-server

# Install dependencies
uv sync

# Test with interactive demo client
python demo.py

# Run automated tests
python demo.py --mode test

# Start server for Claude Desktop
python -m my_server.server --transport stdio

# Start HTTP server
python -m my_server.server --transport http --port 8000

Use with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": ["--directory", "/path/to/my-server", "run", "my_server.server"]
    }
  }
}

Restart Claude Desktop and your tools are ready! 🎉

📖 What Gets Generated?

my-server/
├── my_server/
│   ├── server.py                      # Main entry point (all transports)
│   ├── server_stdio.py                # stdio-only server
│   ├── server_http.py                 # HTTP server with auth
│   ├── server_sse.py                  # SSE server with SSL/TLS
│   ├── interfaces/                    # Abstract base classes
│   │   ├── tool.py
│   │   ├── resource.py
│   │   └── prompt.py
│   ├── services/                      # Business logic layer
│   │   ├── tool_service.py
│   │   ├── resource_service.py
│   │   ├── prompt_service.py
│   │   ├── auth_service.py           # OAuth 2.1 (optional)
│   │   ├── root_service.py           # Roots (optional)
│   │   └── completion_service.py     # Completions (optional)
│   ├── tools/                         # Tool implementations
│   │   ├── add_numbers.py            # Basic arithmetic
│   │   ├── weather_tool.py           # Structured outputs
│   │   ├── reasoning_tool.py         # Sampling (optional)
│   │   ├── greeting_elicitation.py   # Elicitation (optional)
│   │   └── ...
│   ├── resources/                     # Resource implementations
│   │   ├── hello_world.py
│   │   └── user_profile.py
│   └── prompts/                       # Prompt implementations
│       ├── code_review.py
│       └── ...
├── demo.py                            # Interactive demo client
├── completions.py                     # Completion handlers (optional)
├── roots_config.py                    # Roots config (optional)
├── auth_config.py                     # Auth config (optional)
├── pyproject.toml                     # uv project config
└── README.md                          # Project documentation

💡 Examples

Adding a Simple Tool

# my_server/tools/calculator.py
from pydantic import BaseModel, Field
from my_server.interfaces.tool import Tool, ToolResponse, ToolContent

class CalculatorInput(BaseModel):
    expression: str = Field(..., description="Math expression to evaluate")

class CalculatorTool(Tool):
    name = "calculator"
    description = "Evaluates mathematical expressions"
    input_model = CalculatorInput

    async def execute(self, input_data: CalculatorInput) -> ToolResponse:
        try:
            result = eval(input_data.expression)
            return ToolResponse(
                content=[ToolContent.text(f"Result: {result}")]
            )
        except Exception as e:
            return ToolResponse(
                content=[ToolContent.text(f"Error: {e}")],
                is_error=True
            )

Register in tools/__init__.py and server.py - that's it!

Tool with AI Collaboration

from fastmcp import Context

class ResearchTool(Tool):
    name = "research"
    description = "AI-powered research assistant"
    input_model = ResearchInput

    async def execute(self, input_data: ResearchInput, ctx: Context) -> ToolResponse:
        # Call another AI for help
        response = await ctx.sample(
            messages=[{"role": "user", "content": input_data.query}],
            system_prompt="You are a research expert.",
            temperature=0.7
        )

        # Report progress
        await ctx.report_progress(1.0, "Research complete")

        return ToolResponse(content=[ToolContent.text(response.content)])

Interactive User Input (Elicitation)

class TaskTool(Tool):
    name = "create_task"
    description = "Creates a task with user confirmation"
    input_model = TaskInput

    async def execute(self, input_data: TaskInput, ctx: Context) -> ToolResponse:
        # Ask user for confirmation
        result = await ctx.elicit(
            "Create this task?",
            response_type=None  # Approval only
        )

        if result.action == "accept":
            # Create the task
            return ToolResponse(content=[ToolContent.text("Task created!")])
        else:
            return ToolResponse(content=[ToolContent.text("Cancelled")])

Structured Output

class WeatherData(BaseModel):
    temperature: float
    humidity: int
    condition: str

class WeatherTool(Tool):
    name = "get_weather"
    input_model = WeatherInput
    output_model = WeatherData  # Enables structured output!

    async def execute(self, input_data: WeatherInput) -> ToolResponse:
        weather = WeatherData(
            temperature=72.5,
            humidity=65,
            condition="Sunny"
        )
        return ToolResponse.from_model(weather)

🎓 Documentation

• 📘 Getting Started Guide - Complete walkthrough for new users
• 📙 Quick Reference - One-page cheat sheet for common tasks

External Resources

• 🌐 MCP Specification - Official MCP protocol docs
• 🚀 FastMCP Documentation - FastMCP framework docs
• 🔍 MCP Inspector - Official GUI testing tool
• 🐍 Pydantic - Data validation library

🎨 Project Templates

MCP Forge supports different template configurations:

Feature	Description	Flag
Prompts	Reusable LLM templates	--with-prompts / --no-prompts
Sampling	AI-to-AI collaboration	--with-sampling / --no-sampling
Elicitation	Interactive user input	--with-elicitation / --no-elicitation
Roots	Filesystem boundaries	--with-roots / --no-roots
Completion	Argument autocomplete	--with-completion / --no-completion
Authentication	OAuth 2.1 system	--with-auth / --no-auth

Example Configurations

# Minimal server (just tools and resources)
mcp-forge new minimal-server --no-prompts --no-sampling --no-elicitation

# Full-featured server (everything enabled)
mcp-forge new full-server \
  --with-prompts \
  --with-sampling \
  --with-elicitation \
  --with-auth

# API integration server (auth + completion)
mcp-forge new api-server --with-auth --with-completion

🧪 Testing Your Server

Generated servers include multiple testing options:

1. Interactive Demo Client

python demo.py

Features:

• Menu-driven interface
• Browse and execute all tools
• Read resources
• Generate prompts
• Automated test suite

2. MCP Inspector (Official GUI)

npx @modelcontextprotocol/inspector uv run -m my_server.server

Browser-based GUI for:

• Visual tool execution
• Schema inspection
• Resource browsing
• Config export

3. Manual Testing

# Start server
python -m my_server.server --transport http --port 8000

# Test with curl
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

🚀 Deployment

Docker

FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install uv && uv sync
EXPOSE 8000
CMD ["uv", "run", "python", "-m", "my_server.server", "--transport", "sse", "--port", "8000"]

Systemd

[Unit]
Description=My MCP Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/my-server
ExecStart=/usr/local/bin/uv run python -m my_server.server --transport sse --port 8443
Restart=always

[Install]
WantedBy=multi-user.target

Cloud Platforms

• Railway: One-click deploy from GitHub
• Fly.io: fly launch and deploy
• DigitalOcean: Docker container on App Platform
• AWS/GCP/Azure: Container services or serverless

🌟 Showcase

Built something cool with MCP Forge? We'd love to see it!

Share your projects:

• 💬 Discord Community
• 🐙 GitHub Discussions
• 🐦 Twitter with #MCPForge

🤝 Community & Support

🛠️ Contributing

We love contributions! Here's how you can help:

Ways to Contribute

• 🐛 Report Bugs: Open an issue with detailed reproduction steps
• 💡 Suggest Features: Share your ideas in GitHub Discussions
• 📝 Improve Docs: Fix typos, add examples, clarify explanations
• 🔧 Submit PRs: Add features, fix bugs, improve templates
• ⭐ Star the Repo: Show your support and help others discover MCP Forge

Development Setup

# Clone the repository
git clone https://github.com/KennyVaneetvelde/mcp-forge.git
cd mcp-forge

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint code
ruff check .

# Format code
ruff format .

Contribution Guidelines

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• ✅ Code follows project style (ruff)
• ✅ Tests pass
• ✅ Documentation is updated
• ✅ Commit messages are clear

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Anthropic - For creating the Model Context Protocol
• FastMCP - For the excellent Python MCP framework
• MCP Community - For advancing AI integration standards
• All Contributors - Thank you for making MCP Forge better!

📞 Contact

• 💬 Discord: Join our server
• 🐙 GitHub: Issues • Discussions
• 📧 Email: support@example.com (if applicable)
• 🐦 Twitter: @MCPForge (if applicable)

---

📈 Star History