Let’s get you started with your first GolfMCP project from scratch.

1

Install GolfMCP

Install the Golf MCP framework using pip:

pip install golf-mcp
2

Initialize your project

Create a new GolfMCP project using the init command:

golf init my_awesome_server
cd my_awesome_server

This will create a new directory named my_awesome_server with the following structure:

my_awesome_server/
├── .env                  # Environment variables (e.g., API keys, secrets)
├── golf.json             # Main project configuration
├── pre_build.py          # Optional pre-build script (e.g., for auth setup)
├── prompts/              # Directory for prompt components
│   └── welcome.py
├── resources/            # Directory for resource components
│   ├── current_time.py
│   └── info.py
│   └── weather/
│       ├── common.py
│       ├── current.py
│       └── forecast.py
└── tools/                # Directory for tool components
    ├── github_user.py
    ├── hello.py
    └── payments/
        ├── charge.py
        ├── common.py
        └── refund.py
  • golf.json: Configures your server’s name, port, transport, etc.
  • .env: Stores environment-specific variables (automatically created).
  • tools/, resources/, prompts/: Directories where you’ll define your server’s capabilities.
  • pre_build.py: An optional script for custom logic before building, often used for authentication setup.
3

Set up authentication

The boilerplate example includes a GitHub user tool that requires authentication. You can choose between two authentication methods:

  1. Create a GitHub OAuth App by following GitHub’s OAuth App creation guide

  2. Configure the OAuth App URLs (for local testing):

    • Homepage URL: http://127.0.0.1:3000
    • Authorization callback URL: http://127.0.0.1:3000/auth/callback

  3. Set up environment variables in your .env file:

    GITHUB_CLIENT_ID="your-client-id"
GITHUB_CLIENT_SECRET="your-client-secret"
JWT_SECRET="example-jwt-secret-for-development-only"

    Replace the values above with your actual GitHub OAuth app credentials.

  4. Access the token in your tools using:

    from golf.auth.helpers import get_provider_token

token = get_provider_token()
4

Create your first tool

Let’s modify the example “hello” tool. Open tools/hello.py:

"""Hello World tool for {{project_name}}."""

from typing import Annotated
from pydantic import BaseModel, Field


class Output(BaseModel):
    """Response from the hello tool."""
    
    message: str


async def hello(
    name: Annotated[str, Field(description="The name of the person to greet")] = "World",
    greeting: Annotated[str, Field(description="The greeting phrase to use")] = "Hello"
) -> Output:
    """Say hello to the given name.
    
    This is a simple example tool that demonstrates the basic structure
    of a tool implementation in GolfMCP.
    """
    # The framework will add a context object automatically
    # You can log using regular print during development
    print(f"{greeting} {name}...")
    
    # Create and return the response
    return Output(message=f"{greeting}, {name}!")

# Designate the entry point function
export = hello

Key points about this tool:

  • Parameter Annotations: We use Annotated with Field to provide descriptions for each parameter. This helps AI agents understand how to use your tool effectively.
  • Output Model: The Output class defines the structure of the response using Pydantic.
  • Export: The export = hello line tells Golf which function to expose as the tool.
5

Build for development

Compile your project for development:

golf build dev

This command:

  • Parses your project files.
  • Transforms them into a FastMCP server structure.
  • Creates a dist/ directory containing the runnable server (server.py) and any necessary supporting files (like auth components).
  • For dev builds, it copies your .env file to the dist/ directory, making environment variables available to the server.
6

Run your server

Execute the built server:

golf run

Congratulations! You’ve built and run your first GolfMCP server.

7

Connect to Claude or Cursor

To use your GolfMCP server with client like Claude Desktop, Cursor, Windsurf or any other client we recommend mcp-remote to SSE server.

Edit your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add your server configuration:

{
  "mcpServers": {
    "my-golf-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:3000/sse"
      ]
    }
  }
}

With API key authentication:

{
  "mcpServers": {
    "my-golf-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:3000/sse",
        "--header",
        "Authorization: Bearer ${GITHUB_TOKEN}"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_token_here"
      }
    }
  }
}