FastMCP Builder - Claude Code Skill

A comprehensive Claude Code skill for building production-ready MCP (Model Context Protocol) servers using the FastMCP Python framework. This skill provides complete reference implementations, working examples, and proven patterns for creating robust MCP servers with tools, resources, prompts, OAuth authentication, and comprehensive testing.

What is FastMCP?

FastMCP is the official high-level Python framework for building MCP servers. It's simpler, faster to develop with, and more maintainable than the low-level MCP SDK. This skill focuses exclusively on FastMCP-based development.

What's Included

This skill contains everything you need to build production-ready FastMCP servers:

1. Reference Documentation (`reference/`)

Six comprehensive guides covering all aspects of FastMCP development:

fastmcp_overview.md - Introduction, when to use FastMCP, key features
project_structure.md - Recommended structure, file organization, DRY patterns
tool_patterns.md - 6 tool patterns with complete examples
resource_patterns.md - 4 resource types (static, dynamic, template, wildcard)
oauth_integration.md - Complete Google OAuth setup guide
testing_guide.md - FastMCP Client testing, patterns, best practices

2. Code Examples (`examples/`)

Runnable examples from minimal to complete servers:

minimal_server.py - Absolute simplest FastMCP server (28 lines)
complete_server_structure.py - Full-featured single-file example with all patterns
test_examples.py - Comprehensive testing examples

3. Complete Reference Project (`reference-project/`)

A full production implementation demonstrating best practices:

6 production-ready tools - Various patterns (sync, async, stateful, with context)
7 resource instances - 4 types (static, dynamic, template, wildcard)
1 universal prompt - Reusable prompt template
145 passing tests - Comprehensive test coverage
OAuth integration - Complete Google OAuth setup
Dual-mode architecture - main.py (with OAuth) + main_noauth.py (local testing)
DRY principle - Uses common.py for component registration

When to Use This Skill

Use this skill when you need to:

Build MCP servers with FastMCP (Python-based development)
Add OAuth authentication (especially Google OAuth for remote access)
Implement production patterns (tools, resources, prompts with best practices)
Set up comprehensive testing (using FastMCP Client for fast, in-memory tests)
Structure larger projects (proper organization and separation of concerns)
Deploy to production (with authentication, error handling, monitoring)

Don't use this skill for:

TypeScript/Node.js MCP servers (use mcp-builder skill instead)
Low-level MCP protocol work (use MCP SDK directly)
Non-FastMCP Python servers (this is FastMCP-specific)

Installation

Option 1: Install via Plugin Marketplace (Recommended)

Register this marketplace in Claude Code:

/plugin marketplace add husniadil/fastmcp-builder

Browse and install:
- Select "Browse and install plugins"
- Choose "fastmcp-builder-skill"
- Select "fastmcp-builder"
- Click "Install now"

Or install directly:

/plugin install fastmcp-builder@fastmcp-builder-skill

Option 2: Manual Installation

Clone or download this repository to your Claude Code skills directory:

cd ~/.claude/skills
git clone https://github.com/husniadil/fastmcp-builder.git

Using the Skill

Once installed, simply reference the skill in your request:

Use the fastmcp-builder skill to create a new MCP server with OAuth authentication

Quick Start

Simple Example

Create a minimal FastMCP server:

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def greet(name: str) -> str:
    """Greet someone by name"""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()

Try the Included Examples

Navigate to the skill directory and run the examples:

# Navigate to skill directory
cd ~/.claude/plugins/marketplaces/fastmcp-builder-skill

# Try the minimal server
python examples/minimal_server.py

# Try the complete server structure
python examples/complete_server_structure.py

# Run with HTTP mode
python examples/complete_server_structure.py --http

Building Your First Server

Phase 1: Planning & Setup

Review FastMCP Overview - Load reference/fastmcp_overview.md
Understand Requirements - What tools, resources, prompts do you need?
Review Project Structure - Load reference/project_structure.md
Set Up Project - Create directory structure and install dependencies

mkdir my-mcp-server && cd my-mcp-server
mkdir -p app/tools app/resources app/prompts tests
uv add fastmcp==2.13.0.1 python-dotenv==1.2.1
uv add --optional test pytest==8.4.2 pytest-asyncio==1.2.0 pytest-mock==3.15.1 httpx==0.28.1

Phase 2: Core Implementation

Implement Configuration (app/config.py) - Environment variables, settings
Implement Tools (app/tools/) - Follow patterns from reference/tool_patterns.md
Implement Resources (app/resources/) - Follow patterns from reference/resource_patterns.md
Implement Prompts (app/prompts/) - Reusable prompt templates
Create Common Registration (app/common.py) - DRY principle for registering components
Create Server Entry Points - main_noauth.py (local) + main.py (OAuth)

Phase 3: OAuth Integration (Optional)

Follow reference/oauth_integration.md for:

Setting up Google OAuth credentials
Implementing GoogleProvider
Testing with ngrok
Configuring Claude Desktop

Phase 4: Testing

Follow reference/testing_guide.md for:

Setting up test structure (tests/conftest.py)
Writing tool tests
Writing resource tests
Writing integration tests
Running tests: uv run pytest tests/ -v

Phase 5: Documentation & Deployment

Write comprehensive README
Create .env.example template
Test OAuth flow
Deploy to production (Railway, Fly.io, VPS)

Project Structure

Recommended structure for FastMCP projects:

my-mcp-server/
├── app/
│   ├── __init__.py
│   ├── config.py           # Configuration & environment variables
│   ├── common.py           # Shared component registration (DRY)
│   ├── main.py             # Server with OAuth
│   ├── main_noauth.py      # Server without OAuth (local testing)
│   ├── tools/              # Tool implementations
│   │   ├── __init__.py
│   │   ├── my_tool.py
│   │   └── ...
│   ├── resources/          # Resource implementations
│   │   ├── __init__.py
│   │   ├── static.py
│   │   └── ...
│   └── prompts/            # Prompt templates
│       ├── __init__.py
│       └── explain.py
├── tests/
│   ├── __init__.py
│   ├── conftest.py         # Test fixtures
│   ├── test_tools.py
│   ├── test_resources.py
│   └── test_integration.py
├── pyproject.toml          # Project dependencies
├── .env.example            # Environment variable template
├── .env                    # Actual environment variables (gitignored)
└── README.md

Tool Patterns

This skill includes 6 proven tool patterns:

Basic Sync Tools - Simple synchronous functions (health checks, queries)
Data Processing Tools - Text analysis, transformations
Tools with Context - Logging, progress tracking, better UX
Stateful Tools - Counters, session management
API Integration Tools - External service calls
Advanced Async Tools - Complex workflows, parallel processing

See reference/tool_patterns.md for complete examples.

Resource Patterns

This skill includes 4 resource types:

Static Resources - Fixed content (status, features, documentation)
Dynamic Resources - Generated content (current time, computed data)
Template Resources - Path parameters (user://{user_id})
Wildcard Resources - Multi-segment paths (docs://{path*})

See reference/resource_patterns.md for complete examples.

OAuth Integration

Complete guide for adding Google OAuth authentication:

Setting up Google Cloud Console
Implementing GoogleProvider
Testing with ngrok
Configuring Claude Desktop Connectors
Production deployment considerations

See reference/oauth_integration.md for the complete guide.

Testing

Comprehensive testing guide using FastMCP Client:

Fast, in-memory testing (no server startup required)
Tool testing patterns
Resource testing patterns
Integration testing patterns
Achieving >80% test coverage

See reference/testing_guide.md for complete examples.

Best Practices

Use FastMCP - Simpler than MCP SDK for most use cases
Follow project structure - Use common.py pattern (DRY principle)
Dual-mode servers - main.py (OAuth) + main_noauth.py (local)
Comprehensive testing - Use FastMCP Client, aim for >80% coverage
Clear documentation - Docstrings, README, usage examples
Error handling - Graceful failures, informative error messages
Context usage - Logging, progress for better UX
Security - Environment variables, never commit secrets

Common Workflows

Creating a New Tool

Create app/tools/my_tool.py
Implement tool function
Add to app/common.py registration
Write tests in tests/test_tools.py
Run tests: uv run pytest tests/test_tools.py -v

Adding OAuth

Review reference/oauth_integration.md
Set up Google OAuth credentials
Update app/config.py with OAuth settings
Modify app/main.py to use GoogleProvider
Test with ngrok
Configure Claude Desktop Connectors

Debugging

Use main_noauth.py for faster local testing
Add logging with Context: await ctx.debug(...)
Write tests to isolate issues
Check tool/resource registration in common.py
Verify environment variables loaded

Reference Project Details

The reference-project/ directory contains a complete production implementation:

Name: mcp-auth-demo
Version: 1.0.0
Tools: 6 (ping, counter, process_text, analyze_text, get_forecast, request_info)
Resources: 7 instances across 4 types
Prompts: 1 universal prompt template
Tests: 145 passing tests with comprehensive coverage
Features: OAuth, dual-mode architecture, DRY principle, comprehensive error handling

Use this as a reference when building your own servers.

Additional Resources

FastMCP Documentation: https://gofastmcp.com/
FastMCP GitHub: https://github.com/jlowin/fastmcp
MCP Specification: https://modelcontextprotocol.io/
Google OAuth Guide: https://developers.google.com/identity/protocols/oauth2
Claude Code Skills: https://docs.claude.com/en/docs/claude-code/skills.md

Requirements

Python 3.11+
FastMCP 2.13.0.1
python-dotenv 1.2.1

For testing:

pytest 8.4.2
pytest-asyncio 1.2.0
pytest-mock 3.15.1
httpx 0.28.1

Contributing

This is a Claude Code skill. To contribute:

Test changes with the reference project
Ensure all examples run successfully
Update documentation as needed
Add tests for new patterns

License

This skill is provided as-is for use with Claude Code. See LICENSE file for details.

The FastMCP framework itself is licensed separately - see the FastMCP repository for details.

Notes

This skill focuses on FastMCP, not the low-level MCP SDK
All examples use Python 3.11+
OAuth examples use Google OAuth (other providers possible)
Testing uses FastMCP Client (in-memory, fast)
Deployment examples are production-ready

Happy building!

fastmcp-builder