AI导哈

SurrealDB的MCP服务器

SurrealMCP是SurrealDB和SurrealDB Cloud的官方模型上下文协议服务器，使AI助手、AI代理、开发者IDE、AI聊天机器人和数据平台能够与SurrealDB数据库和SurrealDB Cloud进行交互。

  • by dittertp
  • Rust
  • 本地部署
  • 更新于
在 GitHub 查看 dittertp/surrealmcp

使用说明


The official MCP server for SurrealDB.


SurealMCP

SurealMCP是官方的模型上下文协议(主控程序)SurrealDB和SurrealDB Cloud的服务器，使人工智能助手、人工智能代理、开发人员IDE、人工智能聊天机器人和数据平台能够与SurrealDB数据库和SurealDB Cloud进行交互。

特性

  • 多种运输方式：支持 stdioHTTP和Unix套接字连接
  • 认证：使用SurrealDB Cloud进行承载令牌身份验证
  • 速率限制：可配置的请求速率限制
  • 健康检查：内置健康检查
  • 结构化日志记录：全面的日志记录和指标
  • OpenTetry支持：支持 stdio 和OpenTetry跟踪
  • SurrealDB端点锁定：仅允许连接到特定的SurrealDB端点

安装

从源头构建

cargo install --path .

使用Docker部署

docker run --rm -i --pull always surrealdb/surrealmcp:latest start

AI编码工具集成

SurrealMCP可以与各种AI编码工具和助手集成，以实现AI驱动的数据库操作。下面是流行的AI编码平台的安装和配置说明。

你正在使用哪种人工智能助手？

关键术语

  • MCP服务器：实现模型上下文协议的服务器，允许AI助手访问外部工具和资源。
  • MCP客户端：连接到MCP服务器的IDE、应用程序（如Cursor、Zed或Claude Desktop）。
  • SurrealDB：一个具有实时功能的可扩展、分布式文档图数据库。

光标安装

Cursor的安装

  1. 安装SurealMCP：

  1. 配置光标：

    • 打开的游标
    • 前往“设置”>“光标设置”
    • 找到MCP服务器选项并启用它
    • 点击“新建MCP服务器”

  2. 添加SurealMCP配置：

    {
  "name": "SurrealDB",
  "command": "docker",
  "args": [
    "run",
    "--rm",
    "-i",
    "--pull", "always",
    "surrealdb/surrealmcp:latest",
    "start"
  ]
}
    Configuration with environment variables 
    {
  "name": "SurrealDB",
  "command": "surrealmcp",
  "args": ["start"],
  "env": {
    "SURREALDB_URL": "ws://localhost:8000/rpc",
    "SURREALDB_NS": "myapp",
    "SURREALDB_DB": "production",
    "SURREALDB_USER": "admin",
    "SURREALDB_PASS": "password123"
  }
}

  3. 验证安装：

    • 打开光标聊天
    • 您应该在工具列表中看到可用的SurrealDB工具

克劳德安装

Claude桌面应用程序的安装

  1. 安装SurealMCP：

  1. 配置Claude桌面：

    编辑Claude Desktop App的MCP设置文件：

    • 窗户： %APPDATA%\Claude\claude_desktop_config.json
    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux： ~/.config/Claude/claude_desktop_config.json

    添加以下配置：

    {
  "mcpServers": {
    "SurrealDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}
    Configuration with environment variables 
    {
  "mcpServers": {
    "SurrealDB": {
      "command": "surrealmcp",
      "args": ["start"],
      "env": {
        "SURREALDB_URL": "ws://localhost:8000/rpc",
        "SURREALDB_NS": "myapp",
        "SURREALDB_DB": "production",
        "SURREALDB_USER": "admin",
        "SURREALDB_PASS": "password123"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

  2. 验证安装：

    • 请Claude“列出可用的MCP服务器”
    • 您应该在列表中看到“SurrealDB”

副驾驶安装

在VS代码中安装GitHub Copilot

  1. 安装SurealMCP：

  1. 配置VSCode：

    在以下位置创建文件： .vscode/mcp.json 在您的工作空间中

    添加以下配置：

    {
  "servers": {
    "SurrealDB": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ]
    }
  }
}
    Configuration with environment variables 
    {
  "inputs": [
    {
      "type": "promptString",
      "id": "surrealdb-url",
      "description": "SurrealDB URL",
      "default": "ws://localhost:8000/rpc"
    },
    {
      "type": "promptString",
      "id": "surrealdb-ns",
      "description": "SurrealDB Namespace"
    },
    {
      "type": "promptString",
      "id": "surrealdb-db",
      "description": "SurrealDB Database"
    },
    {
      "type": "promptString",
      "id": "surrealdb-user",
      "description": "SurrealDB Username"
    },
    {
      "type": "promptString",
      "id": "surrealdb-pass",
      "description": "SurrealDB Password",
      "password": true
    }
  ],
  "servers": {
    "SurrealDB": {
      "type": "stdio",
      "command": "surrealmcp",
      "args": ["start"],
      "env": {
        "SURREALDB_URL": "${input:surrealdb-url}",
        "SURREALDB_NS": "${input:surrealdb-ns}",
        "SURREALDB_DB": "${input:surrealdb-db}",
        "SURREALDB_USER": "${input:surrealdb-user}",
        "SURREALDB_PASS": "${input:surrealdb-pass}"
      }
    }
  }
}

  2. 验证安装：

    • 在VS代码中打开GitHub Copilot聊天
    • 从下拉菜单中选择“代理”模式
    • 点击“工具”按钮查看可用工具
    • 您应该在列表中看到“SurrealDB”工具

Zed安装

Zed的安装

  1. 安装SurealMCP：

  1. 添加SurealMCP配置：

    "surreal": {
   "command": "docker",
   "args": [
     "run",
     "--rm",
     "-i",
     "--pull", "always",
     "surrealdb/surrealmcp:latest",
     "start"
   ],
   "enabled": true,
 }
    Configuration with environment variables 
    "surreal": {
   "command": "surrealmcp",
   "args": ["start"],
   "enabled": true,
   "env": {
     "SURREALDB_URL": "ws://localhost:8000/rpc",
     "SURREALDB_NS": "myapp",
     "SURREALDB_DB": "production",
     "SURREALDB_USER": "admin",
     "SURREALDB_PASS": "password123"
   }
 }

与n8n集成

您可以将SurealMCP与 n8n 使用 MCP客户端工具 节点。

使用Docker进行部署

将Docker与STDIO结合使用

在不安装的情况下使用SurealMCP cargo 你可以使用Docker。SurrealMCP通过stdio使用单个Docker命令在本地运行。使用临时或持久数据，直接从您的AI工具在边缘立即启动内存或本地数据库。

{
  "mcpServers": {
    "SurrealDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start"
      ]
    }
  }
}

将Docker与HTTP结合使用

在不安装的情况下使用SurealMCP cargo 你可以使用Docker。SurrealMCP可以作为HTTP服务器运行，只需一个Docker命令。使用临时或持久数据，直接从您的AI工具在边缘立即启动内存或本地数据库。

{
  "mcpServers": {
    "SurrealDB": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-p", "8080:8080",
        "--pull", "always",
        "surrealdb/surrealmcp:latest",
        "start",
        "--bind-address", "127.0.0.1:8080",
        "--server-url", "http://localhost:8080"
      ]
    }
  }
}

[！重要] 如果你正在使用Docker Desktop，你可能需要使用 host.docker.internal 而不是 localhost 当为MCP服务器指定要连接的SurrealDB实例URL时。

用法

基本用法

# Start as a STDIO server (default)
surrealmcp start

# Start as a HTTP server
surrealmcp start --bind-address 127.0.0.1:8000

# Start as a Unix socket
surrealmcp start --socket-path /tmp/surrealmcp.sock

配置选项

# Database connection
surrealmcp start \
  --endpoint ws://localhost:8000/rpc \
  --ns mynamespace \
  --db mydatabase \
  --user root \
  --pass root

# Server configuration
surrealmcp start \
  --bind-address 127.0.0.1:8000 \
  --server-url https://mcp.surrealdb.com \
  --cloud-auth-server https://auth.surrealdb.com \
  --expected-audience https://custom.audience.com/ \
  --rate-limit-rps 100 \
  --rate-limit-burst 200

# Disable authentication (for development)
surrealmcp start --bind-address 127.0.0.1:8000 --auth-disabled

环境变量

所有配置选项都可以通过环境变量进行设置：

export SURREALDB_URL="ws://localhost:8000/rpc"
export SURREALDB_NS="mynamespace"
export SURREALDB_DB="mydatabase"
export SURREALDB_USER="root"
export SURREALDB_PASS="root"
export SURREAL_MCP_BIND_ADDRESS="127.0.0.1:8000"
export SURREAL_MCP_SERVER_URL="https://mcp.surrealdb.com"
export SURREAL_CLOUD_AUTH_SERVER="https://auth.surrealdb.com"
export SURREAL_MCP_EXPECTED_AUDIENCE="https://custom.audience.com/"
export SURREAL_MCP_RATE_LIMIT_RPS="100"
export SURREAL_MCP_RATE_LIMIT_BURST="200"
export SURREAL_MCP_AUTH_REQUIRED="false"
export SURREAL_MCP_CLOUD_ACCESS_TOKEN="your_access_token_here"
export SURREAL_MCP_CLOUD_REFRESH_TOKEN="your_refresh_token_here"

surrealmcp start

认证

服务器支持SurrealDB Cloud的承载令牌身份验证。启用身份验证时：

  1. JWT代币：使用来自身份验证服务器的JWKS（JSON Web密钥集）验证JWT令牌
  2. JWE代币：验证JWE标头结构和颁发者
  3. 受众验证：验证 aud 对预期观众的索赔
  4. 发卡机构验证：验证 iss 对预期发行人的索赔

自定义受众配置

您可以为JWT令牌验证指定自定义预期受众：

# Set a custom audience
surrealmcp start --expected-audience "https://myapp.com/api"

# Or via environment variable
export SURREAL_MCP_EXPECTED_AUDIENCE="https://myapp.com/api"
surrealmcp start

这在以下情况下很有用：

  • 您的应用程序在JWT令牌中使用自定义受众
  • 您希望将令牌限制到特定应用程序
  • 您正在与自定义身份验证系统集成

预配置的云身份验证令牌

对于SurrealDB Cloud操作，您可以提供预配置的访问和刷新令牌，而不是动态获取它们：

# Set pre-configured tokens
surrealmcp start \
  --access-token "your_access_token_here" \
  --refresh-token "your_refresh_token_here"

# Or via environment variables
export SURREAL_MCP_CLOUD_ACCESS_TOKEN="your_access_token_here"
export SURREAL_MCP_CLOUD_REFRESH_TOKEN="your_refresh_token_here"
surrealmcp start

这在以下情况下很有用：

  • 您有来自以前身份验证流的现有令牌
  • 您希望避免令牌获取过程
  • 您正在无法获取令牌的环境中运行
  • 您希望使用长期令牌进行自动化操作

备注：当同时提供访问和刷新令牌时，服务器将使用这些令牌执行所有SurralDB Cloud API操作，而不是尝试获取新令牌。

客户端集成

与MCP服务器集成时，客户端应：

  1. 发现授权配置:

    curl http://localhost:8000/.well-known/oauth-protected-resource

  2. 向授权服务器请求令牌 使用返回的观众：

    # Example Auth0 token request
curl -X POST https://auth.surrealdb.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "client_secret": "your-client-secret",
    "audience": "https://custom.audience.com/",
    "grant_type": "client_credentials"
  }'

  3. 使用令牌 对于经过身份验证的请求：

    curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/mcp

受众值可确保专门为MCP服务器实例颁发令牌。

可用工具

SurrealMCP提供了一套全面的工具，用于与SurrealDB数据库和SurrealDB Cloud进行交互：

数据库操作

  • 查询：使用参数化输入执行原始SurrealQL查询
  • 选择：使用筛选、排序和分页查询记录
  • 插入：将新记录插入表中
  • 创建：创建具有特定ID的单个记录
  • 更新插入：根据条件创建或更新记录
  • 更新：使用补丁操作修改现有记录
  • 删除：从数据库中删除记录
  • 关联：在记录之间创建关系

连接管理

  • 连接端点：连接到不同的SurealDB端点，包括：
    • 本地实例： memory, file:/path, rocksdb:/path
    • 远程实例： ws://host:port, http://host:port
    • SurrealDB云实例： cloud:instance_id
  • 使用命名空间：在命名空间之间切换
  • 使用数据库：在数据库之间切换
  • 列出命名空间：列出已定义的命名空间
  • 列出数据库：列出已定义的数据库
  • 断开端点连接：关闭当前连接

SurrealDB云运营

  • 列出云组织：获取可用组织
  • 列出云实例：获取组织的实例
  • 创建云实例：创建新的云实例
  • 暂停/恢复云实例：管理实例生命周期
  • 获取云实例状态：检查实例运行状况和备份

云连接功能

新的云连接功能允许您使用 connect_endpoint 工具与 cloud:instance_id 格式：

# Connect to a SurrealDB Cloud instance
connect_endpoint('cloud:abc123def456', 'myapp', 'production')

此功能：

  • 从SurralDB Cloud API自动获取身份验证令牌
  • 连接前验证实例准备就绪
  • 使用临时身份验证令牌建立安全连接
  • 支持命名空间和数据库规范
  • 通过详细的日志记录优雅地处理连接错误

API终点

健康检查

curl http://localhost:8000/health

身份验证发现

curl http://localhost:8000/.well-known/oauth-protected-resource

此端点返回授权服务器配置，包括预期的受众：

{
  "resource": "https://mcp.surrealdb.com",
  "authorization_servers": ["https://auth.surrealdb.com"],
  "bearer_methods_supported": ["header"],
  "audience": "https://mcp.surrealdb.com/"
}

客户应使用 audience 从授权服务器请求令牌时的值。

MCP协议

服务器实现了模型上下文协议，可以与MCP兼容的客户端一起使用。

发展

建筑

cargo build

测试

cargo test

使用Docker运行

docker build -t surrealmcp .
docker run -p 8000:8000 surrealmcp start --bind-address 0.0.0.0:8000

许可证

该项目根据 商业来源许可证.

相关 MCP