create-mcp-server

The create-mcp-server tool provides several automated features for developers:

• Simple CLI: An interactive command-line interface for project scaffolding.
• Claude Desktop Integration: Automatically configures integration with the Claude Desktop app when it is detected on your system.
• Fast Package Management: Leverages uvx for efficient project creation and dependency handling.
• Standardized Structure: Sets up a basic, clean MCP server structure using the Model Context Protocol Python SDK.
• Zero Configuration: Eliminates the need to manually manage project structures or complex dependency trees.

You can use create-mcp-server to scaffold new Model Context Protocol (MCP) server projects. It is recommended to use uvx for a fast, reliable experience without manual dependency management. Alternatively, you can install it via pip.

Prerequisite: You must have UV >= 0.4.10 installed on your machine.

# Using uvx (recommended)
uvx create-mcp-server

# Or using pip
pip install create-mcp-server
create-mcp-server

After running the creation command, the tool will walk you through a setup process. Once complete, a new directory is generated containing a standard Python project structure (including pyproject.toml and a src/ directory).

To initialize the environment and run your newly created server, navigate to the project directory and use uv commands:

# 1. Create the project (follow the interactive prompts)
uvx create-mcp-server

# 2. Enter the project directory
cd my-server

# 3. Sync dependencies and run the server
uv sync --dev --all-extras
uv run my-server

The create-mcp-server tool can automatically update your claude_desktop_config.json to make your new server immediately available in the Claude Desktop app.

When enabled, the tool adds an entry to the mcpServers section of your configuration file. The entry uses uv to run the server, ensuring the correct environment and dependencies are used.

Configuration Format Added:

"mcpServers": {
  "<project_name>": {
    "command": "uv",
    "args": ["--directory", "<absolute_project_path>", "run", "<project_name>"]
  }
}

Supported Platforms:

• Windows: ~/AppData/Roaming/Claude/claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

To use a published MCP server with Claude Desktop, add the server configuration to your claude_desktop_config.json file using the uvx command.

"mcpServers": {
  "{{server_name}}": {
    "command": "uvx",
    "args": [
      "{{server_name}}"
    ]
  }
}

To use a local, unpublished MCP server with Claude Desktop, add the server configuration to your claude_desktop_config.json file.

Config File Locations:

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

Use the uv command with the --directory flag to point to your server's directory.

"mcpServers": {
  "{{server_name}}": {
    "command": "uv",
    "args": [
      "--directory",
      "{{server_directory}}",
      "run",
      "{{server_name}}"
    ]
  }
}

Follow these steps to prepare and distribute your MCP server package using uv:

1. Sync dependencies: Update the lockfile and sync the environment.
2. Build distributions: Create source and wheel distributions in the dist/ directory.
3. Publish to PyPI: Upload the package to PyPI.

PyPI Authentication Options:

• Token: Use --token or the UV_PUBLISH_TOKEN environment variable.
• Username/Password: Use --username/--password flags or UV_PUBLISH_USERNAME/UV_PUBLISH_PASSWORD environment variables.

# 1. Sync dependencies
uv sync

# 2. Build package distributions
uv build

# 3. Publish to PyPI
uv publish

Because MCP servers communicate over stdio, it is recommended to use the MCP Inspector for debugging.

You can launch the inspector using npx. If your project has a defined binary name, use the specific command structure below. Otherwise, replace <command-to-run-your-server> with your server's startup command.

# If a binary name is defined:
npx @modelcontextprotocol/inspector uv --directory {{server_directory}} run {{binary_name}}

# General usage:
npx @modelcontextprotocol/inspector <command-to-run-your-server>

When creating a new project, the --name must follow specific rules to ensure it is a valid Python package name and compatible with pyproject.toml specifications:

• Must consist of ASCII letters, digits, underscores (_), hyphens (-), and periods (.).
• Must not contain spaces.
• Must not start or end with an underscore, hyphen, or period.
• Cannot be empty.