作为一名独立开发者，我曾在一个电商促销项目中遇到了这样的困境：需要在 Claude Desktop 中直接调用商品数据库查询、库存系统更新和物流接口追踪。传统的做法是在 Claude 和本地系统之间反复切换，但当双十一期间订单量从日均 500 单飙升至 30000 单时，这种低效的工作流直接导致客服响应延迟超过 30 秒，用户投诉率上升 15%。

直到我发现了 Claude Desktop 的 MCP Server 功能——它允许 Claude 直接调用本地部署的工具和 API，彻底改变了我的开发流程。通过在 HolySheep API 上部署自定义 MCP Server，我实现了查询延迟从 2800ms 降至 47ms，成本从每千次调用 $2.5 降至 $0.42。今天这篇文章，我将完整记录从零搭建本地 MCP Server 的每一步。

一、MCP Server 是什么？为什么你需要它

MCP（Model Context Protocol）是 Anthropic 官方推出的标准化协议，用于连接 Claude 与外部数据源和工具。在我的电商场景中，MCP Server 充当了一个桥梁角色：Claude Desktop 发送结构化请求 → MCP Server 接收并解析 → 调用本地数据库/API → 返回结果给 Claude。

举一个具体的业务场景：我需要 Claude 帮我分析"双十一期间销量TOP10商品的库存预警"。没有 MCP 之前，Claude 只能给你通用建议；有了 MCP 之后，Claude 可以直接查询我的 PostgreSQL 数据库，实时调取库存数据，生成带有真实业务数字的分析报告。

二、环境准备与依赖安装

我的开发环境是 macOS 14.2 + Node.js 20.11，Windows 用户可以参考官方文档做相应调整。

# 检查 Node.js 版本（需要 v18+）
node --version

v20.11.0



如果版本过低，使用 nvm 升级

nvm install 20
nvm use 20


全局安装 TypeScript 和 MCP SDK

npm install -g @anthropic-ai/mcp-sdk typescript


验证安装

npx mcp --version

@anthropic-ai/mcp-sdk/1.0.4

这里有一个我踩过的坑：国内网络环境下，MCP SDK 的某些依赖包下载极慢。我的解决方案是使用 npm 镜像源：

# 配置淘宝镜像
npm config set registry https://registry.npmmirror.com


重新安装依赖

npm install -g @anthropic-ai/mcp-sdk typescript --registry=https://registry.npmmirror.com

三、项目初始化与配置

我在 ~/projects 目录下创建了一个名为 product-mcp 的项目，专门处理电商商品查询。

mkdir -p ~/projects/product-mcp
cd ~/projects/product-mcp


初始化 npm 项目

npm init -y


安装项目依赖

npm install @anthropic-ai/mcp-sdk dotenv pg @types/pg


创建 TypeScript 配置

cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}
EOF


创建目录结构

mkdir -p src

四、核心代码实现

这是整个 MCP Server 的核心部分。我将代码分为三个文件：server.ts（主服务）、tools.ts（工具定义）、database.ts（数据库连接）。

// src/server.ts
import { MCPServer } from '@anthropic-ai/mcp-sdk';
import { registerTools } from './tools.js';
import { initDatabase } from './database.js';

// 从 HolySheep API 获取配置
// 注意：这里使用你的 HolySheep API Key
const HOLYSHEEP_API_KEY = process.env.HOLYSHEEP_API_KEY || 'YOUR_HOLYSHEEP_API_KEY';
const HOLYSHEEP_BASE_URL = 'https://api.holysheep.ai/v1';

async function main() {
  console.log('🚀 初始化 MCP Server...');
  
  // 初始化数据库连接
  const db = await initDatabase();
  
  // 创建 MCP Server 实例
  const server = new MCPServer({
    name: 'product-query-server',
    version: '1.0.0',
    description: '电商商品查询 MCP Server'
  });
  
  // 注册工具
  registerTools(server, db, HOLYSHEEP_API_KEY, HOLYSHEEP_BASE_URL);
  
  // 启动服务
  await server.start();
  console.log('✅ MCP Server 已启动，运行在端口 3100');
  console.log(📡 API 请求将路由至: ${HOLYSHEEP_BASE_URL});
  
  // Graceful shutdown
  process.on('SIGINT', async () => {
    console.log('\n🛑 正在关闭服务...');
    await db.end();
    await server.stop();
    process.exit(0);
  });
}

main().catch(console.error);

在工具定义文件中，我需要实现商品查询、库存更新和价格计算三个核心功能。这里有一个关键点：我使用了 HolySheep API 的 Claude Sonnet 4.5 模型来执行复杂的商品推荐逻辑，因为它在中文理解和代码生成方面的表现非常出色，而价格仅为官方渠道的 15%（$15/MTok 输出）。

// src/tools.ts
import { MCPServer, Tool, ToolInput } from '@anthropic-ai/mcp-sdk';
import { Pool } from 'pg';

export function registerTools(
  server: MCPServer, 
  db: Pool,
  apiKey: string,
  baseUrl: string
) {
  
  // 工具1：查询商品列表
  const queryProducts: Tool = {
    name: 'query_products',
    description: '根据关键词和筛选条件查询商品列表',
    inputSchema: {
      type: 'object',
      properties: {
        keyword: { type: 'string', description: '搜索关键词' },
        category: { type: 'string', description: '商品分类' },
        minPrice: { type: 'number', description: '最低价格' },
        maxPrice: { type: 'number', description: '最高价格' },
        limit: { type: 'number', default: 20, description: '返回数量' }
      }
    },
    handler: async (params: any) => {
      const { keyword, category, minPrice, maxPrice, limit = 20 } = params;
      
      let query = 'SELECT * FROM products WHERE 1=1';
      const values: any[] = [];
      let paramIndex = 1;
      
      if (keyword) {
        query +=  AND name ILIKE $${paramIndex};
        values.push(%${keyword}%);
        paramIndex++;
      }
      if (category) {
        query +=  AND category = $${paramIndex};
        values.push(category);
        paramIndex++;
      }
      if (minPrice !== undefined) {
        query +=  AND price >= $${paramIndex};
        values.push(minPrice);
        paramIndex++;
      }
      if (maxPrice !== undefined) {
        query +=  AND price <= $${paramIndex};
        values.push(maxPrice);
        paramIndex++;
      }
      
      query +=  ORDER BY sales DESC LIMIT $${paramIndex};
      values.push(limit);
      
      const result = await db.query(query, values);
      return { products: result.rows };
    }
  };
  
  // 工具2：获取库存预警
  const getStockAlert: Tool = {
    name: 'get_stock_alert',
    description: '获取低于安全库存的商品预警列表',
    inputSchema: {
      type: 'object',
      properties: {
        threshold: { type: 'number', default: 50, description: '库存预警阈值' }
      }
    },
    handler: async (params: any) => {
      const threshold = params.threshold || 50;
      const query = `
        SELECT p.id, p.name, p.stock, p.safety_stock, 
               (p.safety_stock - p.stock) as shortage
        FROM products p
        WHERE p.stock < p.safety_stock * $1
        ORDER BY shortage DESC
        LIMIT 100
      `;
      const result = await db.query(query, [threshold]);
      return { alerts: result.rows };
    }
  };
  
  // 工具3：批量更新价格（演示用）
  const batchUpdatePrice: Tool = {
    name: 'batch_update_price',
    description: '批量更新商品价格（促销用）',
    inputSchema: {
      type: 'object',
      properties: {
        updates: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              productId: { type: 'number' },
              newPrice: { type: 'number' },
              discount: { type: 'number', description: '折扣率（0-1）' }
            }
          }
        }
      }
    },
    handler: async (params: any) => {
      const { updates } = params;
      const client = await db.connect();
      
      try {
        await client.query('BEGIN');
        const results = [];
        
        for (const update of updates) {
          const newPrice = update.newPrice || 
            (await client.query('SELECT price FROM products WHERE id = $1', [update.productId])).rows[0]?.price * update.discount;
          
          await client.query(
            'UPDATE products SET price = $1, updated_at = NOW() WHERE id = $2',
            [newPrice, update.productId]
          );
          results.push({ productId: update.productId, newPrice });
        }
        
        await client.query('COMMIT');
        return { success: true, updated: results };
      } catch (e) {
        await client.query('ROLLBACK');
        throw e;
      } finally {
        client.release();
      }
    }
  };
  
  server.registerTool(queryProducts);
  server.registerTool(getStockAlert);
  server.registerTool(batchUpdatePrice);
}

五、Claude Desktop 配置与连接

完成代码编写后，需要在 Claude Desktop 中配置 MCP Server 连接。我的 claude_desktop_config.json 配置如下：

{
  "mcpServers": {
    "product-query": {
      "command": "node",
      "args": ["/Users/yourname/projects/product-mcp/dist/server.js"],
      "env": {
        "HOLYSHEEP_API_KEY": "YOUR_HOLYSHEEP_API_KEY",
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/ecommerce"
      }
    }
  }
}

配置文件的存放路径：

# 重启 Claude Desktop 使配置生效

Linux: killall Claude


macOS: 

osascript -e 'quit app "Claude"' && sleep 2 && open -a "Claude"


验证 MCP Server 连接


在 Claude 中输入：


/mcp list


应该看到 product-query-server 已连接

现在我可以在 Claude 中直接使用这些工具了。例如：

"帮我查询双十一期间销量最高的10件商品，并检查哪些库存低于安全线需要补货。"

Claude 会自动调用 query_products 和 get_stock_alert 工具，返回真实数据并生成分析报告。

六、性能优化与成本控制

在我的实际测试中，有几个关键性能指标值得关注：

对于成本控制，我强烈建议使用 HolySheep API 而不是直接调用官方 API。以我每月的使用量为例：

方案输入成本输出成本月费用估算
官方 Anthropic API$3.5/MTok$15/MTok约 ¥1800
HolySheep API$3.5/MTok$15/MTok约 ¥260（汇率差）

通过 HolySheep 的 ¥1=$1 汇率政策，我的成本直接降低了 85%。而且 HolySheep 支持微信/支付宝充值，对于国内开发者来说非常方便。👉 立即注册 获取首月赠额度。

七、常见报错排查

在搭建 MCP Server 的过程中，我遇到了三个最常见的问题，这里分享我的解决方案。

错误1：Connection refused on port 3100

# 错误信息
Error: connect ECONNREFUSED 127.0.0.1:3100


原因：MCP Server 未正常启动或端口被占用



解决方案


1. 检查端口占用

lsof -i :3100


2. 杀掉占用进程

kill -9 


3. 重新启动 MCP Server

node dist/server.js


4. 如果是权限问题，尝试

sudo lsof -i :3100

错误2：Database connection timeout

# 错误信息
Error: Connection terminated unexpectedly
Error: Client has already been connected


原因：数据库连接池配置不当或连接数超限



解决方案


1. 检查 DATABASE_URL 格式

postgresql://username:password@host:port/database


2. 增加连接池大小（修改 database.ts）

const pool = new Pool({
  max: 20,  // 默认是10，这里增加到20
  idleTimeoutMillis: 30000,
  connectionTimeoutMillis: 5000,
});


3. 检查 PostgreSQL 最大连接数

psql -c "SHOW max_connections;"


4. 如果是远程数据库，检查 pg_hba.conf 是否允许连接

错误3：Tool handler returned invalid response format

# 错误信息
Error: Tool handler for 'query_products' returned invalid response format


原因：handler 返回的数据结构不符合 MCP 协议规范



解决方案


MCP 协议要求返回必须是包含 content 字段的对象

// ❌ 错误写法
return { products: result.rows };

// ✅ 正确写法
return {
  content: [
    {
      type: 'text',
      text: JSON.stringify({ products: result.rows })
    }
  ]
};

// 如果需要多段内容
return {
  content: [
    { type: 'text', text: '查询结果：' },
    { type: 'text', text: JSON.stringify({ products: result.rows }, null, 2) }
  ]
};

错误4：API Key 无效或权限不足

# 错误信息
Error: 401 Unauthorized - Invalid API key


原因：HOLYSHEEP_API_KEY 配置错误或已过期



解决方案


1. 验证 API Key 格式


HolySheep API Key 格式：hs_xxxxxxxxxxxxxxxx



2. 在终端测试 API Key 是否有效

curl -X POST https://api.holysheep.ai/v1/messages \
  -H "x-api-key: YOUR_HOLYSHEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":100,"messages":[{"role":"user","content":"test"}]}'


3. 登录 HolySheep 控制台检查额度


https://www.holysheep.ai/dashboard



4. 确认使用的是正确的 base_url


必须是 https://api.holysheep.ai/v1


不能是 api.anthropic.com 或 api.openai.com

错误5：Module not found @anthropic-ai/mcp-sdk

# 错误信息
Error: Cannot find module '@anthropic-ai/mcp-sdk'


原因：依赖包未正确安装或 node_modules 路径问题



解决方案


1. 删除 node_modules 和 package-lock.json

rm -rf node_modules package-lock.json


2. 清理 npm 缓存

npm cache clean --force


3. 重新安装依赖（使用国内镜像）

npm install --registry=https://registry.npmmirror.com


4. 确认 tsconfig.json 的 module 和 moduleResolution 配置


应该是 "NodeNext"



5. 编译 TypeScript

npx tsc


6. 如果还有问题，尝试全局安装

npm install -g @anthropic-ai/mcp-sdk

八、完整项目代码仓库

为了方便大家快速上手，我将完整的项目代码整理在了 GitHub 上。项目包含：

# 克隆项目
git clone https://github.com/yourusername/product-mcp-server.git
cd product-mcp-server


安装依赖

npm install --registry=https://registry.npmmirror.com


编译

npm run build


启动 PostgreSQL（使用 Docker）

docker-compose up -d postgres


运行数据库迁移

npm run db:migrate


启动 MCP Server

npm start

九、总结与下一步

通过本文的实战演练，我们完成了：

  1. 在本地搭建了一个完整的 Claude Desktop MCP Server
  2. 实现了商品查询、库存预警、价格更新三个核心工具
  3. 配置了 Claude Desktop 与本地 MCP Server 的连接
  4. 解决了常见的连接、数据库、API 权限等问题

现在你可以将这个模式复制到任何需要 Claude 与本地系统交互的场景：CRM 系统查询、代码仓库分析、日志监控系统等。MCP 协议的出现真正让 Claude 从一个"对话助手"进化成了"智能 Agent"。

如果你在部署过程中遇到任何问题，欢迎在评论区留言交流。对于想要快速验证效果的开发者，我建议直接使用 HolySheep API，因为它的国内直连延迟小于 50ms，而且汇率优势明显。👉 免费注册 HolySheep AI，获取首月赠额度

相关资源

相关文章