Neuron MCP

神经元MCP

NeuronDB-PostgreSQL扩展的模型上下文协议服务器，用Go实现

使MCP兼容客户端能够访问NeuronDB矢量搜索、ML算法和RAG功能。

   ](https://github.com/neurondb/neurondb)  

概述

NeuronMCP通过stdio使用JSON-RPC 2.0实现模型上下文协议。它为MCP客户端提供了与NeuronDB交互的工具和资源，包括向量操作、ML模型训练和数据库模式管理。

关键能力

• MCP协议 --具有stdio、HTTP和SSE传输的完整JSON-RPC 2.0实现
• 650+工具 --向量操作、机器学习、RAG、PostgreSQL管理、调试、组合、工作流、插件。看 功能.md.
• 资源 --实时访问模式、模型、索引和系统统计数据
• 企业安全 -JWT、API密钥、OAuth2、速率限制和审核日志记录
• 高性能 --TTL缓存、连接池和优化的查询执行
• 可观测性 --Prometheus指标、结构化日志记录和健康检查

目录

Expand full table of contents

• 概述

- 关键能力

• 文档
• 工具和Claude桌面
• 官方文件
• 特性
• 建筑

- 系统架构 - MCP协议流 - 工具目录概述

• 快速开始
• MCP协议
• 配置
• 工具
• 资源
• 与Claude Desktop一起使用
• 与其他MCP客户端一起使用
• 文档
• 系统要求
• 与NeuronDB集成
• 故障排除
• 安全
• 支持
• 许可证

______________________________________________________________________

文档

• 特性 -完整的功能列表和功能
• 工具和资源目录 -所有工具和资源的完整目录
• 安装指南 -设置和配置指南

工具和Claude桌面

服务器在启动时注册所有可用的工具（650多种工具：vector、ML、RAG、PostgreSQL管理等）。没有环境变量来限制或过滤注册的工具。

克劳德桌面： 一些MCP客户端，包括Claude Desktop，可能会对它们显示或使用的工具数量施加限制。如果达到该限制，请使用不同的MCP客户端（例如随附的 neuron-mcp-client)或者在需要完整工具集的上下文中运行服务器。看 安装指南 用于Claude桌面配置。

示例配置（使用构建的二进制文件的路径，例如。 ./bin/neuron-mcp):

{
  "mcpServers": {
    "neurondb": {
      "command": "/path/to/neuron-mcp",
      "env": {
        "NEURONDB_HOST": "localhost",
        "NEURONDB_PORT": "5432",
        "NEURONDB_DATABASE": "neurondb",
        "NEURONDB_USER": "neurondb",
        "NEURONDB_PASSWORD": "your_password"
      }
    }
  }
}

官方文件

https://www.neurondb.ai/docs/neuronmcp --工具参考、Claude Desktop设置和配置。

特性

Complete Feature List

有关与其他MCP服务器的详细比较，请参阅 docs/tool-resource-catalog.md 和那个 MCP协议规范.

建筑

系统架构

graph TB
    subgraph CLIENT["MCP Clients"]
        CLAUDE[Claude Desktop]
        CUSTOM[Custom MCP Clients]
        CLI[CLI Tools]
    end
    
    subgraph MCP["NeuronMCP Server"]
        PROTOCOL[MCP Protocol Handler
JSON-RPC 2.0]
        TOOLS[Tool Registry
650+ Tools]
        RESOURCES[Resource Manager
Schema, Models, Indexes]
        MIDDLEWARE[Middleware Pipeline
Auth, Logging, Rate Limit]
        CACHE[TTL Cache
Idempotency]
    end
    
    subgraph CATEGORIES["Tool Categories"]
        VEC[Vector Operations
50+ tools]
        ML[ML Pipeline
25+ algorithm families]
        RAG[RAG Operations
Document processing]
        PG[PostgreSQL Tools
100+ DDL/DML/DCL
650+ total tools]
        DATASET[Dataset Loading
HuggingFace, S3, GitHub]
    end
    
    subgraph DB["NeuronDB PostgreSQL"]
        VECTOR[Vector Search
HNSW/IVF]
        EMBED[Embeddings
Text/Image/Multimodal]
        ML_FUNC[ML Functions
25+ algorithm families]
        ADMIN[PostgreSQL Admin
Full DDL/DML/DCL]
    end
    
    CLAUDE -->|stdio| PROTOCOL
    CUSTOM -->|stdio/HTTP/SSE| PROTOCOL
    CLI -->|stdio| PROTOCOL
    
    PROTOCOL --> MIDDLEWARE
    MIDDLEWARE --> CACHE
    CACHE --> TOOLS
    CACHE --> RESOURCES
    
    TOOLS --> VEC
    TOOLS --> ML
    TOOLS --> RAG
    TOOLS --> PG
    TOOLS --> DATASET
    
    VEC --> VECTOR
    ML --> ML_FUNC
    RAG --> EMBED
    PG --> ADMIN
    DATASET --> VECTOR
    
    style CLIENT fill:#e3f2fd
    style MCP fill:#fff3e0
    style CATEGORIES fill:#f3e5f5
    style DB fill:#e8f5e9

MCP协议流

sequenceDiagram
    participant Client as MCP Client
    participant Server as NeuronMCP Server
    participant Tools as Tool Registry
    participant DB as NeuronDB
    
    Client->>Server: Initialize (JSON-RPC)
    Server-->>Client: Server Capabilities
    
    Client->>Server: tools/list
    Server->>Tools: Get available tools
    Tools-->>Server: Tool catalog
    Server-->>Client: Tool list (650+ tools)
    
    Client->>Server: tools/call {"name": "vector_search", ...}
    Server->>Server: Validate & authenticate
    Server->>Tools: Execute tool
    Tools->>DB: Execute SQL query
    DB-->>Tools: Query results
    Tools-->>Server: Tool response
    Server-->>Client: JSON-RPC response
    
    Note over Client,DB: Streaming supported via SSE

工具目录概述

graph LR
    subgraph TOOLS["650+ Tools"]
        VEC_TOOLS[Vector Operations
Search, Embeddings, Indexing]
        ML_TOOLS[ML Pipeline
25+ algorithm families
Training, Prediction, Evaluation]
        RAG_TOOLS[RAG Operations
Document Processing
Context Retrieval]
        PG_TOOLS[PostgreSQL Tools
100+ tools
DDL, DML, DCL, Admin]
        DATASET_TOOLS[Dataset Loading
HuggingFace, S3, GitHub
Auto-embedding]
    end
    
    style VEC_TOOLS fill:#ffebee
    style ML_TOOLS fill:#e8f5e9
    style RAG_TOOLS fill:#fff3e0
    style PG_TOOLS fill:#e3f2fd
    style DATASET_TOOLS fill:#f3e5f5

使用 安装指南 克劳德桌面。如果您的客户端限制了工具的数量，请使用另一个MCP客户端，如附带的 neuron-mcp-client.

快速开始

先决条件

Prerequisites Checklist

• \[\]已安装PostgreSQL 16或更高版本
• \[\]NeuronDB扩展已安装并启用
• \[\]转到1.23或更高版本（用于从源代码构建）
• \[\]MCP兼容客户端（例如，Claude Desktop）
• \[\]已配置API密钥（用于LLM模型，如果使用嵌入/RAG）

数据库设置

选项1：使用Docker Compose（建议快速入门）

如果你有PostgreSQL和NeuronDB（例如来自 神经元b repo Docker设置）：

# Create extension if not already created
psql "postgresql://neurondb:neurondb@localhost:5433/neurondb" -c "CREATE EXTENSION IF NOT EXISTS neurondb;"

选项2：原生PostgreSQL安装

createdb neurondb
psql -d neurondb -c "CREATE EXTENSION neurondb;"

Neuron MCP可以为LLM模型配置、API键、索引模板、工作者设置和工具默认值使用可选的数据库模式。跑 ./scripts/neuronmcp-setup.sh 从存储库根目录进行设置。看 neurondb-mcp-setup.md 了解详情。

配置

创建 mcp-config.json:

{
  "database": {
    "host": "localhost",
    "port": 5433,
    "database": "neurondb",
    "user": "neurondb",
    "password": "neurondb"
  },
  "server": {
    "name": "neurondb-mcp-server",
    "version": "2.0.0"
  },
  "logging": {
    "level": "info",
    "format": "text"
  },
  "features": {
    "vector": { "enabled": true },
    "ml": { "enabled": true },
    "analytics": { "enabled": true }
  }
}

或者使用环境变量：

export NEURONDB_HOST=localhost
export NEURONDB_PORT=5432
export NEURONDB_DATABASE=neurondb
export NEURONDB_USER=neurondb
export NEURONDB_PASSWORD=neurondb

构建并运行

运行服务器

从存储库根目录：

make build
export NEURONDB_HOST=localhost NEURONDB_PORT=5432 NEURONDB_DATABASE=neurondb NEURONDB_USER=neurondb NEURONDB_PASSWORD=neurondb
./bin/neuron-mcp

可选：传递一个配置文件 -c 或设置 NEURONDB_MCP_CONFIG 走向你的道路 mcp-config.json.

测试：运行附带的客户端以列出工具：

./bin/neuron-mcp-client ./bin/neuron-mcp tools/list

或者发送原始JSON-RPC初始化以确认服务器响应：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./bin/neuron-mcp

自动设置（推荐）

使用数据库架构的安装脚本（可选LLM/config表）：

# From repository root
./scripts/neuronmcp-setup.sh

# With system service enabled (if supported)
./scripts/neuronmcp-setup.sh --enable-service

使用 scripts/neuronmcp-run.sh 或 scripts/neuronmcp-run-server.sh 运行服务器。

手动构建（无Makefile）

go build -o bin/neuron-mcp ./cmd/neurondb-mcp
./bin/neuron-mcp

使用Docker

此回购不包括 docker-compose.yml。手动构建并运行映像：

# From repository root
docker build -f docker/Dockerfile -t neurondb-mcp:latest .

docker run -i --rm \
  -e NEURONDB_HOST=localhost \
  -e NEURONDB_PORT=5432 \
  -e NEURONDB_DATABASE=neurondb \
  -e NEURONDB_USER=neurondb \
  -e NEURONDB_PASSWORD=neurondb \
  neurondb-mcp:latest

对于全栈Docker（NeuronDB+NeuronMCP），请使用NeuronDB存储库或从其存储库中部署每个组件。

作为服务运行

对于systemd（Linux）或launchd（macOS），请参阅您的系统文档或 neurondb安装服务指南 对于模式。

MCP协议

NeuronMCP在stdio上使用模型上下文协议：

• 通过stdin和stdout进行通信
• 消息遵循JSON-RPC 2.0格式
• 客户端发起所有请求
• 服务器返回结果或错误

请求示例：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "vector_search",
    "arguments": {
      "query_vector": [0.1, 0.2, 0.3],
      "table": "documents",
      "limit": 10
    }
  }
}

配置

环境变量

配置文件

看 mcp-config.json.example 以获得完整的配置结构。环境变量覆盖配置文件值。

工具

NeuronMCP提供全面的工具，涵盖NeuronDB的所有功能：

工具参考： 工具和资源目录. PostgreSQL工具： docs/postgresql-tools.md.

例如，客户端使用和交互记录，请参见 文档/示例/.

数据集加载示例

这 load_dataset 该工具支持多个数据源，具有自动模式检测、嵌入生成和索引创建功能：

HuggingFace数据集

{
  "name": "load_dataset",
  "arguments": {
    "source_type": "huggingface",
    "source_path": "sentence-transformers/embedding-training-data",
    "split": "train",
    "limit": 10000,
    "auto_embed": true,
    "embedding_model": "default"
  }
}

URL数据集（CSV、JSON、Parquet）

{
  "name": "load_dataset",
  "arguments": {
    "source_type": "url",
    "source_path": "https://example.com/data.csv",
    "format": "csv",
    "auto_embed": true,
    "create_indexes": true
  }
}

GitHub存储库

{
  "name": "load_dataset",
  "arguments": {
    "source_type": "github",
    "source_path": "owner/repo/path/to/data.json",
    "auto_embed": true
  }
}

S3铲斗

{
  "name": "load_dataset",
  "arguments": {
    "source_type": "s3",
    "source_path": "s3://my-bucket/data.parquet",
    "auto_embed": true
  }
}

本地文件

{
  "name": "load_dataset",
  "arguments": {
    "source_type": "local",
    "source_path": "/path/to/local/file.jsonl",
    "schema_name": "my_schema",
    "table_name": "my_table",
    "auto_embed": true
  }
}

主要特点：

• 自动模式检测：分析数据类型并创建优化的PostgreSQL表
• 自动嵌入：使用NeuronDB自动检测文本列并生成向量嵌入
• 索引创建：为向量创建HNSW索引，为全文搜索创建GIN索引
• 批量加载：高效的批量装载和进度跟踪
• 多种格式：支持CSV、JSON、JSONL、Parquet和HuggingFace数据集

资源

NeuronMCP公开以下资源：

与Claude Desktop一起使用

NeuronMCP与macOS、Windows和Linux上的Claude Desktop完全兼容。

创建Claude Desktop配置文件：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

窗户： %APPDATA%\Claude\claude_desktop_config.json

Linux： ~/.config/Claude/claude_desktop_config.json

请参阅此目录中的示例配置文件(claude_desktop_config.*.json)针对特定平台的示例。

配置示例：

{
  "mcpServers": {
    "neurondb": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network", "neurondb-network",
        "-e", "NEURONDB_HOST=neurondb-cpu",
        "-e", "NEURONDB_PORT=5432",
        "-e", "NEURONDB_DATABASE=neurondb",
        "-e", "NEURONDB_USER=neurondb",
        "-e", "NEURONDB_PASSWORD=neurondb",
        "neurondb-mcp:latest"
      ]
    }
  }
}

或者使用本地二进制：

{
  "mcpServers": {
    "neurondb": {
      "command": "/path/to/neuron-mcp",
      "env": {
        "NEURONDB_HOST": "localhost",
        "NEURONDB_PORT": "5432",
        "NEURONDB_DATABASE": "neurondb",
        "NEURONDB_USER": "neurondb",
        "NEURONDB_PASSWORD": "neurondb"
      }
    }
  }
}

使用构建二进制文件的完整路径（例如。 /home/user/neuron-mcp/bin/neuron-mcp).

配置更改后重新启动Claude Desktop。

与其他MCP客户端一起使用

以交互方式运行NeuronMCP进行测试：

./bin/neuron-mcp

通过stdin发送JSON-RPC消息，通过stdout接收响应。

使用神经元mcp客户端

一个像Claude Desktop一样工作的简单MCP客户端。它处理完整的MCP协议，包括初始化握手。

构建客户端（包含在 make build):

make build

用途：

# Initialize and list tools
./bin/neuron-mcp-client ./bin/neuron-mcp tools/list

# Call a tool
./bin/neuron-mcp-client ./bin/neuron-mcp tools/call '{"name":"vector_search","arguments":{}}'

# List resources
./bin/neuron-mcp-client ./bin/neuron-mcp resources/list

客户端自动：

• 发送带有正确标头的初始化请求（与Claude Desktop完全相同）
• 读取初始化响应
• 读取初始化通知
• 然后发送您的请求并读取响应

测试脚本：

cd src/client
./example_usage.sh

或者使用Python客户端：

cd src/client
python neurondb_mcp_client.py -c ../tests/neuronmcp_server.json -e "list_tools"

对于Docker：

docker run -i --rm \
  -e NEURONDB_HOST=localhost \
  -e NEURONDB_PORT=5432 \
  -e NEURONDB_DATABASE=neurondb \
  -e NEURONDB_USER=neurondb \
  -e NEURONDB_PASSWORD=neurondb \
  neurondb-mcp:latest

先建立形象： docker build -f docker/Dockerfile -t neurondb-mcp:latest . 从存储库根目录。

文档

系统要求

与NeuronDB集成

故障排除

标准不起作用

确保stdin和stdout未被重定向：

./bin/neuron-mcp  # Correct
./bin/neuron-mcp > output.log  # Incorrect - breaks MCP protocol

对于Docker，使用交互模式：

docker run -i --rm neurondb-mcp:latest

数据库连接失败

验证连接参数：

psql -h localhost -p 5432 -U neurondb -d neurondb -c "SELECT 1;"

检查环境变量：

env | grep NEURONDB

MCP客户端连接问题

验证容器是否正在运行（如果从另一个仓库使用Docker）：

docker ps | grep neurondb-mcp

手动测试stdio：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./bin/neuron-mcp

检查客户端配置文件路径和格式。

配置问题

验证配置文件路径：

ls -la mcp-config.json

检查环境变量名称（必须以开头 NEURONDB_):

env | grep -E "^NEURONDB_"

安全

• 通过环境变量安全存储的数据库凭据
• 支持加密数据库连接的TLS/SSL
• Docker容器中的非root用户
• 无网络端点（仅限stdio）

支持

• 文档：此自述文件和 文档 目录
• GitHub问题: 报告问题
• 电子邮件: support@neurondb.ai

许可证

看 许可证 获取许可证信息。

______________________________________________________________________

返回页首