MCP Factory

An extensible Model Context Protocol (MCP) server framework with a service plugin architecture. Built with FastMCP and Python 3.13. Ships with a NASA APOD (Astronomy Picture of the Day) service as a reference implementation.

Add new API services by implementing a plugin -- your tools appear automatically in every MCP client. Fork the repo to build your own production MCP server from a solid, SOLID foundation.

Bundled Service: NASA APOD

The included APOD service demonstrates the plugin pattern with these features:

Get Today's Photo — Fetch the current Astronomy Picture of the Day with title, explanation, and media link.
Get Photo by Date — Retrieve any APOD entry from the archive (1995-06-16 to today) by providing a date.
Get Random Photo — Discover a random APOD from NASA's 30+ year archive.
Famous Space Dates Resource — A curated list of iconic space exploration dates to explore in the APOD archive.

Tools

| Tool | Description | |------|-------------| | get_todays_space_photo | Returns today's APOD with title, explanation, media type, and URL | | get_space_photo_by_date | Returns the APOD for a specific date (YYYY-MM-DD format) | | get_random_space_photo | Returns a random APOD from the full archive |

Resources

| URI | Description | |-----|-------------| | space://events/famous-dates | Curated list of famous space exploration dates |

Prerequisites

Python 3.13+
uv (recommended package manager)

Installation

git clone <your-repo-url>
cd mcp-factory
uv sync

Usage

Running the server standalone

uv run main.py

The server communicates over stdio transport, which is the standard for MCP client integrations.

Adding to Cursor IDE

Add the following to your Cursor MCP settings (.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-factory": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-factory",
        "main.py"
      ]
    }
  }
}

Replace /absolute/path/to/mcp-factory with the actual path to this project on your machine.

Adding to Claude Desktop

Add the following to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-factory": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-factory",
        "main.py"
      ]
    }
  }
}

API Key

The bundled APOD service uses NASA's DEMO_KEY by default, which has limited rate limits (30 requests/hour, 50 requests/day per IP). For heavier usage, request a free API key and set the NASA_API_KEY environment variable:

export NASA_API_KEY="your-key-here"

Project Structure

mcp-factory/
├── main.py                         # Thin entry point — starts the MCP server
├── mcp_factory/                      # Core package
│   ├── __init__.py
│   ├── config.py                   # Global config (server name)
│   ├── server.py                   # Builds FastMCP via ServiceRegistry
│   └── services/                   # Service plugin architecture
│       ├── __init__.py
│       ├── base.py                 # ABCs: BaseAPIClient, BaseFormatter, ServicePlugin
│       ├── registry.py             # ServiceRegistry factory
│       └── apod/                   # APOD service plugin
│           ├── __init__.py         # ApodService (registers tools + resources)
│           ├── config.py           # APOD-specific constants and API key
│           ├── client.py           # ApodClient (extends BaseAPIClient)
│           ├── formatter.py        # ApodFormatter (extends BaseFormatter)
│           └── validation.py       # APOD date validation
├── tests/                          # Unit + E2E tests (pytest)
│   ├── test_base.py                # ABC contract tests
│   ├── test_registry.py            # ServiceRegistry factory tests
│   ├── test_apod_config.py         # APOD config constants
│   ├── test_apod_client.py         # ApodClient with mocked HTTP
│   ├── test_apod_formatter.py      # ApodFormatter output
│   ├── test_apod_validation.py     # Date validation
│   └── test_e2e.py                 # Full server bootstrap + tool execution
├── templates/                      # Copy-paste service boilerplate
│   ├── README.md                   # Template usage instructions
│   └── service_template/           # Complete service plugin skeleton
├── docs/                           # Guides, architecture, and workshop
│   ├── ARCHITECTURE.md             # System design and SOLID mapping
│   ├── ADDING-A-SERVICE.md         # Step-by-step new service guide
│   ├── ADDING-TOOLS.md             # Tool and resource creation guide
│   ├── FORKING-GUIDE.md            # Using this repo as a template
│   ├── DEVELOPMENT-WORKFLOW.md     # Git, testing, and review workflow
│   ├── LETS-BUILD-AN-MCP-SERVER.md # Original step-by-step tutorial
│   └── index.html                  # Slide deck presentation
├── CLAUDE.md                       # AI agent context (Claude Code, etc.)
├── pyproject.toml                  # Project metadata and dependencies
├── uv.lock                         # Locked dependency versions
├── .python-version                 # Python version (3.13)
├── .gitignore                      # Git ignore rules
└── README.md                       # This file

Extending with a New API Service

This server uses a service plugin architecture. Each API is a self-contained plugin under mcp_factory/services/. To add a new API:

Create a new directory: mcp_factory/services/your_api/
Implement a client extending BaseAPIClient (handles HTTP)
Implement a formatter extending BaseFormatter (handles Markdown output)
Create a service class with a register(mcp) method that registers your tools
Add it to the registry in mcp_factory/server.py:

from mcp_factory.services.your_api import YourApiService

registry.add(YourApiService())

Your new tools appear automatically -- no other files need to change.

Documentation

For Developers

| Guide | Description | |-------|-------------| | Architecture | System design, plugin lifecycle, data flow, SOLID principles, module map | | Adding a Service | Step-by-step guide to adding a new API service plugin | | Adding Tools | How to add tools and resources to an existing service | | Forking Guide | Using this repo as a template for a new MCP server | | Development Workflow | Git workflow, testing strategy, code review checklist | | Tutorial | Original step-by-step MCP server tutorial |

For AI Agents

| Resource | Description | |----------|-------------| | CLAUDE.md | Root-level context file for Claude Code and agentic frameworks | | .cursor/rules/architecture.mdc | Always-on architecture context for Cursor AI | | .cursor/rules/extending-services.mdc | Step-by-step instructions triggered when extending services | | .cursor/rules/mcp-factory-tools.mdc | Tool routing rules for bundled APOD service |

Boilerplate Templates

Copy-paste-ready service skeleton at templates/service_template/. See templates/README.md for usage.

Dependencies

mcp[cli] — Model Context Protocol SDK with CLI support
httpx — Async HTTP client for external API calls

License

This project is for educational and personal use. The bundled APOD service uses data from NASA's APOD API.

MCP Servers