Golf

⛳ Golf

Easiest framework for building MCP servers











<strong>📚 Documentation</strong>

Overview

Golf is a framework designed to streamline the creation of MCP server applications. It allows developers to define server's capabilities—tools, prompts, and resources—as simple Python files within a conventional directory structure. Golf then automatically discovers, parses, and compiles these components into a runnable MCP server, minimizing boilerplate and accelerating development.

Golf targets FastMCP 4.0.0 and the current MCP 2026-07-28 protocol. FastMCP also negotiates legacy MCP clients through its compatibility mode.

With Golf v0.2.0, you get enterprise-grade authentication (JWT, OAuth Server, development tokens), built-in utilities for LLM interactions, and automatic telemetry integration. Focus on implementing your agent's logic while Golf handles authentication, monitoring, and server infrastructure.

Quick Start

Get your Golf project up and running in a few simple steps:

1. Install Golf

Golf requires Python 3.10 or newer. Then, install Golf using pip:

pip install golf-mcp

2. Initialize Your Project

Use the Golf CLI to scaffold a new project:

golf init your-project-name

This command creates a new directory (your-project-name) with a basic project structure, including example tools, resources, and a golf.json configuration file.

3. Run the Development Server

Navigate into your new project directory and start the development server:

cd your-project-name
golf build dev
golf run

This will start the MCP server, typically on http://localhost:3000 (configurable in golf.json).

That's it! Your Golf server is running and ready for integration.

Basic Project Structure

A Golf project initialized with golf init will have a structure similar to this:

<your-project-name>/
│
├─ golf.json          # Main project configuration
│
├─ tools/             # Directory for tool implementations
│   └─ hello.py       # Example tool
│
├─ resources/         # Directory for resource implementations
│   └─ info.py        # Example resource
│
├─ prompts/           # Directory for prompt templates
│   └─ welcome.py     # Example prompt
│
├─ .env               # Environment variables (e.g., API keys, server port)
└─ auth.py            # Authentication configuration (JWT, OAuth Server, API key, dev tokens)

• golf.json: Configures server name, port, transport, telemetry, and other build settings.
• auth.py: Dedicated authentication configuration file (new in v0.2.0, breaking change from v0.1.x authentication API) for JWT, OAuth Server, API key, or development authentication.
• tools/, resources/, prompts/: Contain your Python files, each defining a single component. These directories can also contain nested subdirectories to further organize your components (e.g., tools/payments/charge.py). The module docstring of each file serves as the component's description.
  • Component IDs are automatically derived from their file path. For example, tools/hello.py becomes hello, and a nested file like tools/payments/submit.py would become submit_payments (filename, followed by reversed parent directories under the main category, joined by underscores).

Example: Defining a Tool