---
title: 配置 MCP Server：让 Claude Code 可控接入本地知识库
description: 用 Claude Code 的项目级 stdio 配置连接 ChatCrystal MCP，核对七个工具、HTTP 后端、审批和真实调用链路。
image: "https://zengliangyi.com/og/blog/chatcrystal-mcp-setup.png"
---

ChatCrystal 的 MCP 入口是一个 stdio 桥接层：Claude Code 启动 `crystal mcp` 子进程，子进程再通过 HTTP 调用 ChatCrystal Server。stdio 不等于整个链路没有网络，也不等于工具每次都会自动调用；配置、服务健康和具体请求都要分别验收。

本文依据 [MCP server 实现](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/cli/mcp/server.ts)、[CLI 命令](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/cli/commands/mcp.ts) 和固定提交 [`7642768`](https://github.com/ZengLiangYi/ChatCrystal/tree/764276814e5c5a33ecbfeae63754f74b9261a3a8)。Claude Code 的安装命令和作用域以[官方 MCP 文档](https://code.claude.com/docs/en/mcp)为准。

## 先启动可访问的 ChatCrystal 服务

CLI 要求 Node.js 24 或更高版本；安装后在默认本机连接上启动服务：



```bash
npm   install   -g   chatcrystal  
  crystal   serve   --daemon  
  crystal   status
```



`crystal mcp` 启动时会先请求服务状态，再注册 stdio 工具。默认本机连接的服务未运行时，客户端会尝试后台启动并等待就绪；其他连接不会这样启动。健康或状态检查最终失败时，MCP 不会进入正常工具通信阶段。默认本机端口是 3721。若使用云端连接，应通过 CLI 的 token/base URL 连接配置完成认证；不要把真实 token 写进项目文件。应用当前对自定义回环地址有连接限制，先以实际 `crystal status` 和连接配置为准。

## 用 Claude Code 项目作用域注册

官方 CLI 使用 `--` 把 Claude Code 的选项与 stdio 命令参数分开。项目作用域会写入项目根目录的 `.mcp.json`，适合团队审阅和共享：



```bash
claude   mcp   add   --scope   project   --transport   stdio   chatcrystal   --   crystal   mcp  
  claude   mcp   list  
  claude   mcp   get   chatcrystal
```



首次使用项目级服务器可能需要在 Claude Code 中批准工作区。也可以检查 `.mcp.json` 内容，但不要把 API token 或机器特定路径提交到仓库。官方文档说明了 local、project、user 三种作用域及其优先级；如果只想本机使用，可省略 `--scope project` 使用 local 作用域。

## 核对七个工具的实际边界

服务器注册以下工具：

- `search_knowledge`：语义检索，默认上限 10。

- `get_note`：按 ID 读取完整笔记。

- `list_notes`：每页最多 20 条，支持标签和标题/摘要筛选。

- `get_relations`：读取某条笔记的关系。

- `recall_for_task`：将有界全库检索的候选筛选为项目记忆与全局补充。

- `validate_task_memory`：写回前的无副作用质量预检。

- `write_task_memory`：把有具体结论的经验写回知识库。

工具结果以 MCP text content 返回 JSON 字符串，不是文章里可以直接假定的任意结构化对象。`list_notes` 的搜索筛选沿用 API 的 SQL LIKE 语义；需要语义排序时调用 `search_knowledge`。自动写回会严格拒绝一次性状态报告、模糊日志和不可复用的内容；手动模式仍有结构校验，但标题、摘要和结论可读时，可能带质量警告接受。接受结果也不代表经验已经被当前项目验证。

## 明白 stdio 与 HTTP 的关系



```text
Claude Code  
    │ MCP stdio  
    ▼  
  crystal mcp  
    │ HTTP (CrystalClient)  
    ▼  
  ChatCrystal Server :3721  
    └─ SQLite + Vectra
```



crystal mcp 是 Claude Code 启动的 stdio 子进程。协议消息占用 stdout，诊断日志写入 stderr；不要在 MCP 进程里向 stdout 打印调试文本。桥接进程依赖 HTTP 服务的可达性、认证和超时，stdio 只描述 Claude Code 与桥接进程之间的传输。

## 逐层验收连接

先运行 `crystal status`，再在 Claude Code 中执行：



```text
/mcp
```



查看 `chatcrystal` 的连接状态和工具数量。随后用一个知识库中确实存在的问题请求 `search_knowledge`，再用返回的 ID 调 `get_note`；不要只凭列表里出现服务器名称就宣称检索成功。最后可用一个有具体结论的构造记忆先调用 `validate_task_memory`，确认质量门槛后再决定是否写回。

Claude Code 能调用工具不保证每次自然语言请求都会自动调用它。需要确定性流程时，在项目规则或任务步骤中明确要求先回忆、展示来源、再验证后写回。更多任务记忆边界见 [Agent 知识记忆闭环](/blog/agent-knowledge-memory-loop)。

分享：

##  相关文章

[##  基于 MCP 的 Claude Code 记忆工作流：回忆、验证与写回

用 recall_for_task、validate_task_memory 和 write_task_memory 组织可审计的任务记忆流程，不把工具配置误当成自动记忆保证。          曾亮懿       2026年10月3日      阅读约 4 分钟

#ChatCrystal

#MCP

#Claude Code](/blog/claude-code-memory-workflow)    [##  深入 Model Context Protocol 规范：服务发现与鉴权

对照 ChatCrystal 的七个 MCP 工具，用固定 SDK 的内存传输验证同名工具可指向不同实例，并区分参数 schema、行为提示与应用权限。          曾亮懿       2026年10月7日      阅读约 4 分钟

#ChatCrystal

#MCP

#Node.js](/blog/mcp-protocol-boundaries)    [##  从零实现最小 MCP Server：工具注册与 stdio 协议调用

用固定版本 TypeScript SDK 编写一个离线加法工具，从客户端完成初始化、发现、调用与参数错误检查，再对照 ChatCrystal 的适配边界。          曾亮懿       2026年10月6日      阅读约 4 分钟

#ChatCrystal

#MCP

#Node.js](/blog/mcp-server-implementation)

##  从文章到代码

到我的 GitHub 看看 ChatCrystal、开发者工具和日常学习记录，欢迎交流实现细节。

[访问我的 GitHub](https://github.com/ZengLiangYi)

```json
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "ZengLiangYi Blog",
  "alternateName": [
    "Zeng Liangyi",
    "ZengLiangYi",
    "zengliangyi.com"
  ],
  "url": "https://zengliangyi.com",
  "description": "曾亮懿的个人网站。记录 AI Native 探索、开发者工具与全栈产品实践。"
}
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "配置 MCP Server：让 Claude Code 可控接入本地知识库",
  "description": "用 Claude Code 的项目级 stdio 配置连接 ChatCrystal MCP，核对七个工具、HTTP 后端、审批和真实调用链路。",
  "url": "https://zengliangyi.com/blog/chatcrystal-mcp-setup/",
  "image": "https://zengliangyi.com/images/blog/chatcrystal-mcp-setup.svg",
  "datePublished": "2026-10-03T00:00:00.000Z",
  "dateModified": "2026-10-23T00:00:00.000Z",
  "author": {
    "@type": "Person",
    "name": "曾亮懿",
    "url": "https://zengliangyi.com/about"
  },
  "publisher": {
    "@type": "Organization",
    "name": "ZengLiangYi Blog",
    "logo": {
      "@type": "ImageObject",
      "url": "https://zengliangyi.com/favicon-96x96.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://zengliangyi.com/blog/chatcrystal-mcp-setup/"
  }
}
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "首页",
      "item": "https://zengliangyi.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "文章",
      "item": "https://zengliangyi.com/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "配置 MCP Server：让 Claude Code 可控接入本地知识库",
      "item": "https://zengliangyi.com/blog/chatcrystal-mcp-setup/"
    }
  ]
}
```