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)

1. Register this marketplace in Claude Code:

   hljs language-bash

   Copy

   /plugin marketplace add husniadil/fastmcp-builder
   

2. Browse and install:

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

3. Or install directly:

   hljs language-bash

   Copy

   /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

1. Review FastMCP Overview - Load reference/fastmcp_overview.md
2. Understand Requirements - What tools, resources, prompts do you need?
3. Review Project Structure - Load reference/project_structure.md
4. 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

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

Phase 3: OAuth Integration (Optional)

Follow reference/oauth_integration.md for:

1. Setting up Google OAuth credentials
2. Implementing GoogleProvider
3. Testing with ngrok
4. Configuring Claude Desktop

Phase 4: Testing

Follow reference/testing_guide.md for:

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

Phase 5: Documentation & Deployment

1. Write comprehensive README
2. Create .env.example template
3. Test OAuth flow
4. 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:

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

See reference/tool_patterns.md for complete examples.

Resource Patterns

This skill includes 4 resource types:

1. Static Resources - Fixed content (status, features, documentation)
2. Dynamic Resources - Generated content (current time, computed data)
3. Template Resources - Path parameters (user://{user_id})
4. 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

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

Common Workflows

Creating a New Tool

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

Adding OAuth

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

Debugging

1. Use main_noauth.py for faster local testing
2. Add logging with Context: await ctx.debug(...)
3. Write tests to isolate issues
4. Check tool/resource registration in common.py
5. 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:

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

License

MIT License - Copyright 2025 Husni Adil Makmur

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!