MCP Advisor 快速开始指南

July 12, 2025 · View on GitHub

这是 MCP Advisor 的完整安装、配置和使用指南，让您快速上手并充分利用 MCP Advisor 的功能。

目录

安装方式

通过 MCP 配置集成（推荐）

最快的方式是通过 MCP 配置集成 MCP Advisor：

{
  "mcpServers": {
    "mcpadvisor": {
      "command": "npx",
      "args": ["-y", "@xiaohui-wang/mcpadvisor"]
    }
  }
}

将此配置添加到您的 AI 助手的 MCP 设置文件中：

  • MacOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %AppData%\Claude\claude_desktop_config.json

配置完成后重启您的 AI 助手即可使用。

NPM 包安装

如果您需要在项目中集成 MCP Advisor：

# 使用 npm
npm install @xiaohui-wang/mcpadvisor

# 使用 yarn
yarn add @xiaohui-wang/mcpadvisor

# 使用 pnpm
pnpm add @xiaohui-wang/mcpadvisor

全局安装

全局安装可以在任何地方使用 mcpadvisor 命令：

# 全局安装
npm install -g @xiaohui-wang/mcpadvisor

# 运行
mcpadvisor

直接使用

无需安装直接使用：

# 使用 npx 运行（无需安装）
npx @xiaohui-wang/mcpadvisor

# 或者使用 npx 运行特定版本
npx @xiaohui-wang/mcpadvisor@latest

通过 Smithery 安装

使用 Smithery 自动安装到 Claude Desktop：

npx -y @smithery/cli install @istarwyh/mcpadvisor --client claude

基本使用

寻找 MCP 服务器

MCP Advisor 允许您通过自然语言查询发现和使用 MCP 服务器。以下是使用方法：

1. 直接查询

向您的 AI 助手询问特定任务的 MCP 服务器：

哪些 MCP 服务器可以用于向量数据库集成？

Find MCP servers for natural language processing

2. 功能导向查询

请求具有特定功能的服务器：

找一个用于图像生成的 MCP 服务器

I need an MCP server for image generation

3. 任务导向查询

描述您想要完成的任务：

我需要分析金融数据，应该使用哪个 MCP 服务器？

I need to analyze financial data, which MCP server should I use?

理解搜索结果

MCP Advisor 返回的结果包含以下信息：

  • 服务器名称: MCP 服务器的名称
  • 描述: 服务器功能的简要说明
  • GitHub URL: 服务器仓库的链接
  • 安装说明: 如何安装和配置服务器
  • 相关性评分: 服务器与您查询的匹配程度

结果示例

[
  {
    "title": "NLP Toolkit",
    "description": "Comprehensive natural language processing toolkit with sentiment analysis, entity recognition, and text summarization capabilities.",
    "github_url": "https://github.com/example/nlp-toolkit",
    "similarity": 0.92
  }
]

与 AI 助手集成

Claude Desktop

  1. 配置 MCP Advisor：

    将以下配置添加到 claude_desktop_config.json：

    {
  "mcpServers": {
    "mcpadvisor": {
      "command": "npx",
      "args": ["-y", "@xiaohui-wang/mcpadvisor"]
    }
  }
}

  2. 重启 Claude Desktop

  3. 开始使用：

    Claude，请帮我找一个用于数据库操作的 MCP 服务器

其他 AI 助手

对于支持 Model Context Protocol 的其他 AI 助手：

  1. 全局安装 MCP Advisor：

    npm install -g @xiaohui-wang/mcpadvisor

  2. 配置助手使用 MCP Advisor 作为服务器

  3. 参考您的助手文档了解具体的 MCP 集成步骤

配置选项

环境变量配置

MCP Advisor 可以使用以下环境变量进行配置。所有环境变量都是可选的，除非另有说明。

核心配置

变量描述默认值必需
TRANSPORT_TYPE传输方法 (stdio, sse, rest)stdio否
LOG_LEVEL日志级别 (debug, info, warn, error)info否
DEBUG启用调试日志false否
ENABLE_FILE_LOGGING启用文件日志false否

HTTP 服务器配置（SSE/REST 传输）

变量描述默认值必需
SERVER_PORTHTTP 服务器端口3000否
SERVER_HOSTHTTP 服务器主机localhost否
SSE_PATHSSE 端点路径/sse否
MESSAGE_PATH消息端点路径/messages否
ENDPOINTREST 端点路径/rest否

搜索配置

变量描述默认值必需
MIN_SIMILARITY搜索结果的最小相似度分数0.5否
MAX_RESULTS返回的最大搜索结果数10否
ENABLE_CACHE启用搜索结果缓存false否
CACHE_TTL缓存结果的生存时间（秒）3600否
VECTOR_ENGINE_TYPE向量引擎类型 (memory, oceanbase, meilisearch)memory否

API 配置

变量描述默认值必需
COMPASS_API_BASECOMPASS API 的基础 URLhttps://registry.mcphub.io否
OCEANBASE_URLOceanBase 数据库连接字符串-使用 OceanBase 时必需

Nacos Provider 配置

如果您选择使用 Nacos 作为搜索提供者：

环境变量描述默认值必填
NACOS_SERVER_ADDRNacos 服务器地址无是
NACOS_NAMESPACENacos 命名空间public否
NACOS_GROUPNacos 分组DEFAULT_GROUP否
NACOS_USERNAMENacos 用户名无如果 Nacos 需要认证
NACOS_PASSWORDNacos 密码无如果 Nacos 需要认证
MCP_SERVICE_NAMEMCP 服务在 Nacos 中的名称mcp-servers否

日志配置

变量描述默认值必需
LOG_DIR日志文件目录./logs否

配置文件设置

您也可以使用配置文件进行设置。创建 .mcpadvisorrc.json 文件：

{
  "transport": "stdio",
  "port": 3000,
  "enableFileLogging": true,
  "logLevel": "info",
  "vectorEngineType": "memory",
  "search": {
    "provider": "hybrid",
    "limit": 5,
    "minSimilarity": 0.3
  }
}

或者使用 config/default.json：

{
  "server": {
    "port": 3000,
    "transportType": "stdio"
  },
  "search": {
    "provider": "hybrid",
    "limit": 5,
    "minSimilarity": 0.3
  }
}

传输方式配置

MCP Advisor 支持多种传输方式：

1. Stdio Transport（默认）

适用于命令行工具：

node build/index.js

2. SSE Transport

适用于 Web 集成：

TRANSPORT_TYPE=sse SERVER_PORT=3000 DEBUG=true ENABLE_FILE_LOGGING=true node build/index.js

3. REST Transport

提供 RESTful 端点：

TRANSPORT_TYPE=rest SERVER_PORT=8080 ENDPOINT=/api/mcp node build/index.js

生产配置示例

TRANSPORT_TYPE=rest SERVER_PORT=8080 SERVER_HOST=0.0.0.0 LOG_LEVEL=warn ENABLE_FILE_LOGGING=true node build/index.js

使用技巧

高效查询技巧

为了从 MCP Advisor 获得最佳结果：

1. 具体化描述

包含关键功能需求：

找一个支持多语言的 OCR MCP 服务器

Find an MCP server for OCR with support for multiple languages

2. 包含领域上下文

提及您的应用领域：

需要一个具有合规功能的金融数据分析 MCP 服务器

MCP server for financial data analysis with regulatory compliance features

3. 指定技术要求

包含任何技术限制：

找一个轻量级的离线图像处理 MCP 服务器

Find a lightweight MCP server for image processing that works offline

高级搜索选项

当以编程方式使用 MCP Advisor 时，您可以指定其他搜索参数：

const results = await searchService.search("vector database", {
  limit: 10,
  minSimilarity: 0.2,
  includeMetadata: true
});

常见问题排查

安装问题

1. 权限错误

如果遇到权限错误，请尝试使用管理员权限：

# macOS/Linux
sudo npm install -g @xiaohui-wang/mcpadvisor

# Windows (以管理员身份运行命令提示符)
npm install -g @xiaohui-wang/mcpadvisor

2. 版本冲突

如果与其他包有版本冲突：

npm install @xiaohui-wang/mcpadvisor --force

3. 找不到命令

确保全局 npm bin 目录在您的 PATH 中：

# 查看 npm 全局路径
npm bin -g

# 添加到 PATH（macOS/Linux）
export PATH="$PATH:$(npm bin -g)"

# Windows
set PATH=%PATH%;%APPDATA%\npm

配置问题

1. MCP 配置不生效

检查配置文件路径：

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

确保 JSON 格式正确：

# 验证 JSON 格式
cat ~/.../claude_desktop_config.json | python -m json.tool

2. 环境变量不生效

确认环境变量设置：

# Linux/macOS
echo $TRANSPORT_TYPE
export TRANSPORT_TYPE=sse

# Windows
echo %TRANSPORT_TYPE%
set TRANSPORT_TYPE=sse

运行时问题

1. 连接被拒绝

确保服务器运行在指定端口并检查防火墙设置：

# 检查端口占用
netstat -an | grep 3000
lsof -i :3000

# 检查服务状态
curl http://localhost:3000/health

2. 搜索无结果

尝试更通用的查询：

# 从具体查询
"advanced machine learning vector database with GPU acceleration"

# 改为通用查询  
"machine learning" 或 "vector database"

检查网络连接：

# 测试外部 API 连接
curl -I https://api.getmcp.org
ping registry.mcphub.io

3. 性能问题

考虑以下优化：

  • 使用更具体的搜索词
  • 检查服务器资源（CPU/内存）
  • 启用缓存：ENABLE_CACHE=true
  • 调整搜索限制：MAX_RESULTS=5

验证安装

运行以下命令验证安装：

# 检查版本
mcpadvisor --version

# 或者
npx @xiaohui-wang/mcpadvisor --version

# 测试基本功能
mcpadvisor --help

如果显示版本号和帮助信息，则表示安装成功。

如果您遇到本指南未涵盖的问题，请：

  1. 查看 故障排除文档
  2. 检查 GitHub Issues
  3. 创建新的 Issue 寻求帮助

更多高级配置和技术细节，请参阅：