MCP Server

Build the MCP server with pnpm --filter "@kit/mcp-server" build. AI tools like Claude Code, Cursor, and Windsurf will automatically detect it via .mcp.json and gain access to component discovery, script guidance, and PRD management tools.

This guide is part of the Next.js Prisma SaaS Kit installation.

The Makerkit MCP Server helps AI Agents code with the codebase by providing a set of tools for discovering UI components, running scripts, and managing Product Requirements Documents (PRDs).

Setup

The MCP Server is already configured in the .mcp.json file - but before being able to run it, we need to build it with the following command:

pnpm --filter "@kit/mcp-server" build

AI Agents should pick it up right away, but if they don't, make sure to add them manually using the same format as .mcp.json:

{
  "mcpServers": {
    "makerkit": {
      "type": "stdio",
      "command": "node",
      "args": ["tooling/mcp-server/build/index.js"]
    }
  }
}

Available Tools

The MCP Server provides three categories of tools:

UI Components Tools

Tools for discovering and inspecting the @kit/ui component library.

• get_components - Lists all available UI components with their category (shadcn/makerkit/utils) and descriptions
• get_component_content - Retrieves the full source code of a specific component
• components_search - Searches components by keyword in name, description, or category
• get_component_props - Extracts props, interfaces, and CVA variants from a component

Example usage by AI agents:

• List all components → get_components()
• Search for table-related components → components_search({ query: "table" })
• Get the Button component source → get_component_content({ componentName: "button" })
• Inspect Alert component props → get_component_props({ componentName: "alert" })

Scripts Tools

Tools for understanding available npm/pnpm scripts and their purpose.

• get_scripts - Lists all scripts sorted by importance with usage guidance
• get_script_details - Gets detailed info about a specific script including category and importance
• get_healthcheck_scripts - Returns critical scripts that must run after writing code

Healthcheck scripts are marked as critical and should be run after any code changes:

• typecheck - TypeScript type checking
• lint / lint:fix - ESLint code quality checks
• format:fix - Prettier code formatting
• test - Unit test execution

PRD Management Tools

Tools for creating and managing Product Requirements Documents following ChatPRD best practices. PRDs are stored as JSON files in the .prds directory.

• list_prds - Lists all PRD files in the .prds folder
• get_prd - Retrieves the contents of a specific PRD file
• create_prd - Creates a new structured PRD with title, problem statement, solution, and metrics
• add_user_story - Adds a user story to an existing PRD with acceptance criteria
• update_story_status - Updates a story's status (not_started, research, in_progress, review, completed, blocked)
• export_prd_markdown - Exports the PRD as a formatted markdown file for sharing
• get_implementation_prompts - Generates implementation prompts from user stories
• get_improvement_suggestions - Provides suggestions to improve the PRD
• get_project_status - Returns progress overview, next steps, and blockers

User Story Workflow:

1. Create a PRD with create_prd
2. Add user stories with add_user_story
3. Track progress with update_story_status
4. Generate implementation tasks with get_implementation_prompts
5. Monitor progress with get_project_status

Configuration for AI Tools

Claude Code / Claude Desktop

The .mcp.json file in the project root is automatically detected. Ensure the server is built before starting your AI session.

Cursor

Add to your Cursor MCP settings:

{
  "makerkit": {
    "type": "stdio",
    "command": "node",
    "args": ["/absolute/path/to/project/tooling/mcp-server/build/index.js"]
  }
}

Windsurf

Configure in your Windsurf MCP settings with the same format, using absolute paths to the built server.

Rebuilding the Server

After modifying the MCP server source code in tooling/mcp-server/src, rebuild with:

pnpm --filter "@kit/mcp-server" build

Then restart your AI agent session to pick up the changes.

Common Pitfalls

• Forgot to build the server - The MCP server must be built before use; run pnpm --filter "@kit/mcp-server" build first
• AI agent not detecting .mcp.json - Some agents require a restart after the file is created; close and reopen your AI tool
• Wrong path in Cursor/Windsurf config - Use absolute paths, not relative; the path must point to the built index.js file
• Server crashes on startup - Check that Node.js is available in your PATH and the build completed successfully
• Tools not appearing in AI agent - Rebuild the server and restart the AI session; cached server instances don't pick up changes

Why Use the MCP Server?

• Component Discovery: AI agents can explore available UI components without reading multiple files
• Consistent Patterns: Agents learn component APIs and variants directly from source
• Script Guidance: Agents know which scripts to run and when
• PRD Tracking: Maintain structured requirements that guide implementation
• Reduced Hallucination: Real-time access to actual codebase information

You've completed the installation guide. The MCP Server enhances your development experience with AI-assisted tooling.

Previous: Running the Project