Name: 模型上下文协议服务器
Author: chaitanyakartik

使用说明

Local MCP Server: A Complete Guide

This guide details how to build a local Model Context Protocol (MCP) server, configure it, and connect it to LLM clients like Claude Desktop and VS Code (Copilot).

What is MCP (Model Context Protocol)?

MCP is basically a standard for servers; it's just a web server following a certain template. It provides a standard interface through which LLMs can access tools and data. We basically allow the LLMs to autonomously do custom function calls and data retrieval when they think it's required.

This allows you to give an LLM "tools" — like the ability to roll dice, access a local file, or call a private API — that it can use to answer your questions.

How it Works: The Two-Part System

The key to understanding this setup is knowing that there are two separate components: the Server and the Gateway.

The MCP Server (e.g., dice-mcp-server)
- Analogy: The Chef 👨‍🍳
- This is the Docker image you build. It contains your actual code (e.g., a Python script) that knows how to perform the tasks, like roll_dice. This is the "kitchen" where the work gets done.
The MCP Gateway (e.g., docker/mcp-gateway)
- Analogy: The Manager 👔
- This is an official Docker image that acts as the "manager" or "front counter." It's the only thing the LLM client (Claude/VS Code) talks to. Its job is to read your configuration files and tell the correct "Chef" (your server) what to do.

You build the Chef and configure the Manager.

Architecture Flow

Here is a diagram showing how the user, the client, the gateway, and your server all interact.

graph TB
    subgraph user[" "]
        A["👤 USER<br/><br/>Ask AI anything"]
    end
    
    subgraph client[" "]
        B["💻 AI CLIENT<br/><br/>Claude Desktop<br/>VS Code Copilot<br/>Cursor<br/>Any MCP-enabled app"]
    end
    
    subgraph gateway[" "]
        C["🌉 DOCKER MCP GATEWAY<br/><br/>Smart Orchestrator<br/>📋 Manages multiple servers<br/>🔌 Routes tool requests<br/>⚙️ Handles connections"]
    end
    
    subgraph servers[" "]
        direction LR
        E1["🔧 SERVER 1<br/>Database Tools"]
        E2["🔧 SERVER 2<br/>API Integration"]
        E3["🔧 SERVER 3<br/>File Processing"]
        E4["🔧 SERVER N<br/>Your Custom Logic"]
    end
    
    subgraph examples[" "]
        direction LR
        F["💾 DATABASES<br/>PostgreSQL<br/>MongoDB<br/>Redis<br/>SQLite"]
        G["🌐 EXTERNAL APIS<br/>GitHub<br/>Slack<br/>Payment APIs<br/>Weather, Stock"]
        H["📁 FILE SYSTEMS<br/>Read/Write files<br/>Process CSVs<br/>Generate PDFs<br/>Image manipulation"]
        I["⚡ CUSTOM TOOLS<br/>Business logic<br/>Calculations<br/>Validations<br/>Automation"]
    end

    A ==>|"① Natural language query"| B
    B ==>|"② Discovers available tools<br/>Sends tool request"| C
    C ==>|"③ Routes to appropriate server"| E1 & E2 & E3 & E4
    
    E1 -.->|"accesses"| F
    E2 -.->|"accesses"| G
    E3 -.->|"accesses"| H
    E4 -.->|"accesses"| I
    
    E1 & E2 & E3 & E4 ==>|"④ Executes & returns results"| C
    C ==>|"⑤ Aggregates responses"| B
    B ==>|"⑥ Natural language answer"| A

    classDef userStyle fill:#FF6B6B,stroke:#C92A2A,stroke-width:3px,color:#FFF
    classDef clientStyle fill:#4ECDC4,stroke:#0B7285,stroke-width:3px,color:#FFF
    classDef gatewayStyle fill:#45B7D1,stroke:#1971C2,stroke-width:3px,color:#FFF
    classDef serverStyle fill:#A78BFA,stroke:#6D28D9,stroke-width:2px,color:#FFF
    classDef exampleStyle fill:#FFA07A,stroke:#E8590C,stroke-width:2px,color:#FFF
    
    class A userStyle
    class B clientStyle
    class C gatewayStyle
    class E1,E2,E3,E4 serverStyle
    class F,G,H,I exampleStyle

Prerequisites Check

Docker Desktop installed and running.
An MCP Client (e.g., Claude Desktop or VS Code with Copilot).
Enable Docker MCP Toolkit:
1. Open Docker Desktop.
2. Go to Settings → Beta Features.
3. Enable "Docker MCP Toolkit".
4. Click Apply & Restart.

Step 1: Build Your Tool Server (The "Chef")

First, you need to build the Docker image that contains your actual tool's code.

# Clone the example repository
git clone https://github.com/chaitanyakartik/local_MCP_template.git
cd src

# Build the Docker image, this creates a local image named "dice-mcp-server"
docker build -t dice-mcp-server .

Step 2: Create Your Configuration Files (The "Menu")

This is the most critical part. You must create two files in a specific folder to tell the "Manager" (the Gateway) about your "Chef" (the dice-mcp-server).

Go to your home folder (e.g., /Users/your-name/ or C:\Users\your-name\). Find or create the hidden .docker folder, and inside it, create an mcp folder.

The full path will be:

macOS: /Users/your-name/.docker/mcp
Windows: C:\Users\your-name\.docker\mcp

Inside this mcp folder, create the following:

1. The Registry File (The "Enable" List)

This file tells the Gateway which of your custom servers to turn on.

Create this file: ~/.docker/mcp/registry.yaml
Paste this exact content:
```
  dice:
    ref: ""
```
(Note: The ref: must be indented with two spaces.)

2. The Catalog File (The "Menu")

This file describes your server and its tools.

Create this folder: ~/.docker/mcp/catalogs/
Create this file: ~/.docker/mcp/catalogs/custom.yaml

Paste this exact content:

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  dice:
    description: "Dice rolling for tabletop games"
    title: "Dice Roller"
    type: server
    dateAdded: "2025-01-01T00:00:00Z"
    image: dice-mcp-server:latest
    ref: ""
    tools:
      - name: flip_coin
      - name: roll_dice
      - name: roll_custom
      - name: roll_stats
      - name: roll_advantage
      - name: roll_disadvantage
      - name: roll_check
      - name: roll_initiative
    metadata:
      category: productivity
      tags:
        - gaming
        - dice
        - randomization

Step 3: Connect the LLM Client (The "Manager")

This is where we tell your client (Claude or VS Code) how to run the "Manager" (the Gateway). We will use an explicit command that cannot fail to find your config files.

First, get the full, absolute path to your mcp folder (e.g., /Users/chaitanyakartik/.docker/mcp or C:\Users\YourUser\.docker\mcp).

Option A: Connect to Claude Desktop

Open your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Paste the following JSON. You must replace YOUR_FULL_PATH_HERE with your actual path.

{
  "mcpServers": {
    "docker-mcp-gateway-explicit": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        
        /*
         THIS IS THE CRITICAL LINE.
         It maps your local config folder into the container.
        */
        "-v", "YOUR_FULL_PATH_HERE:/mcp",
        
        "docker/mcp-gateway",
        "--registry=/mcp/registry.yaml",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--transport=stdio"
      ]
    }
  }
}

Windows Users: Remember to use double backslashes (\\) for your path, e.g., "C:\\Users\\YourUser\\.docker\\mcp:/mcp".

Option B: Connect to VS Code (Copilot)

In VS Code, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
Run the command MCP: Open User Configuration.
This will open your mcp.json file.

Paste the following JSON. You must replace YOUR_FULL_PATH_HERE with your actual path.

{
  "servers": {
    "docker-mcp-gateway-explicit": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",

        /*
         THIS IS THE CRITICAL LINE.
         It maps your local config folder into the container.
        */
        "-v",
        "YOUR_FULL_PATH_HERE:/mcp",

        "docker/mcp-gateway",
        "--registry=/mcp/registry.yaml",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--transport=stdio"
      ],
      "type": "stdio"
    }
  },
  "inputs": []
}

Windows Users: Remember to use double backslashes (\\) for your path, e.g., "C:\\Users\\YourUser\\.docker\\mcp:/mcp".

Step 4: Test It!

Completely quit and restart Claude Desktop or VS Code.
Open a new chat.
Click the Tools icon (or press Cmd/Ctrl+I).
You should see your gateway listed: docker-mcp-gateway-explicit.
Under it, you should see all your dice tools: roll_dice, flip_coin, etc.
Try it! "Roll 2d6+3 for damage"

If it works, you have successfully built and configured a local MCP server.

Acknowledgements

This guide and the dice-mcp-server example are heavily based on the excellent tutorial and code provided by NetworkChuck.

GitHub Repository: networkchuck/docker-mcp-tutorial
Original YouTube Tutorial: you need to learn MCP RIGHT NOW!! (Model Context Protocol)

使用说明

Local MCP Server: A Complete Guide

What is MCP (Model Context Protocol)?

How it Works: The Two-Part System

Architecture Flow

Prerequisites Check

Step 1: Build Your Tool Server (The "Chef")

Step 2: Create Your Configuration Files (The "Menu")

1. The Registry File (The "Enable" List)

2. The Catalog File (The "Menu")

Step 3: Connect the LLM Client (The "Manager")

Option A: Connect to Claude Desktop

Option B: Connect to VS Code (Copilot)

Step 4: Test It!

Acknowledgements

相关 MCP

MCP文本编辑器服务

Prometheus数据检索服务器

生物数据查询服务

开放数据协议服务器

Steam 评测检索 MCP 服务

自然语言数据库查询服务