mcp-template

MCP server template for building tools that interface with Claude and other MCP-compatible clients.

Install

# Quick install, creates new directory my-project and runs setup
curl -sL https://raw.githubusercontent.com/plawlost/mcp-template/main/install.sh | bash -s my-project

# Or manual setup
git clone https://github.com/plawlost/mcp-template.git
cd mcp-template
chmod +x setup.sh
./setup.sh

Usage

Build

npm run build

Test directly

node dist/main.js --direct --query="test" --mode=search

Connect to client

Add to Claude config:

// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "your-mcp-name": {
      "command": "node",
      "args": ["/absolute/path/to/dist/main.js"],
      "env": {}
    }
  }
}

Or use Smithery CLI:

npx -y @smithery/cli install /path/to/your/project --client claude

Customization

The template offers two primary capabilities:

1. Tools - Actions that perform tasks
2. Prompts - Templates for LLM interactions

1. Data Types

Define your data interfaces in src/main.ts:

// Line ~16
interface YourDataType {
  id: string;
  name: string;
  description?: string;
  // Add your properties
}

2. Data Functions

Replace the data fetching functions:

// Line ~35
const fetchData = async (query: string): Promise<YourDataType[]> => {
  // Replace with real implementation
}

// Line ~72
async function getMockData(query: string): Promise<YourDataType[]> {
  // Fallback data when real source fails
}

3. Add Tools

Each tool follows this pattern:

server.tool(
  "toolName",                // Name
  "Tool description",        // Description 
  {                          // Parameters with Zod
    param: z.string().describe("Parameter description"),
  },
  async (args, _extra) => {  // Implementation
    const { param } = args;
    // Implementation
    return {
      content: [
        { type: "text", text: "Response text" }
      ]
    };
  }
);

4. Add Prompts

For standardized LLM interactions:

server.prompt(
  "promptName",              
  "Prompt description",      
  {
    param: z.string().describe("Parameter description")
  },
  async (args, _extra) => {
    const { param } = args;
    return {
      messages: [
        {
          role: "user",
          content: { type: "text", text: "Formatted prompt text" }
        }
      ]
    };
  }
);

MCP Clients

• Claude Desktop - Desktop client by Anthropic
• Goose - CLI client by Block
• Cursor - Code-focused IDE with MCP support
• Cline - Terminal client
• Windsurf - Electron-based client

Troubleshooting

• Tool not found: Ensure tool names are exactly as expected
• Parameter errors: Check parameter schemas match what's passed
• Connection issues: Verify paths in client configuration

License

MIT