10 分钟用 TaoToken 跑通 MCP 文件系统 Skill

🚀 告别海外账号与网络限制！稳定直连全球优质大模型，限时半价接入中。 👉 点击领取海量免费额度

1. 任务拆解：filesystem MCP Server 要在 Claude Code 里干什么

这篇把 Claude Code 接到 filesystem MCP Server，模型入口用 TaoToken 的 Key 和 Base URL。真正容易卡住的不是 MCP 协议，而是模型入口和工具入口是两条线：模型入口要走 API 通道，工具入口是 filesystem MCP Server 的本地进程。Claude Code 负责在多轮对话里决定何时调用文件工具，MCP Server 负责按授权目录读文件。这篇的目标很小，10 分钟内让 Claude Code 加载 filesystem MCP，并对一个测试仓库做一次只读检索。没有公榜分数，也不把生产库接进来，操作范围只在你指定的本地目录。

很多人第一次配 MCP 会把两件事混在一起：以为 Claude Code 能读文件，是因为模型能力，其实不是。模型只负责生成「我要调用 search_files」这样的工具调用意图，真正执行搜索的是本机启动的 filesystem MCP Server。Claude Code 把这个 Server 注册进来，再把模型返回的工具调用转发过去，最后把工具结果拼回上下文。模型通道断掉，Claude Code 连话都说不了；MCP 通道断掉，Claude Code 能聊天但摸不到文件。两边分开检查，排障会快很多。

1.1 10 分钟时间盒怎么切

时间盒只是节奏，不是硬指标。网络慢、npx 首次拉包、Claude Code 版本差异都会吃掉一两分钟。比较稳的切法是：前 2 分钟注册拿 Key，并把 Key 放在一个不会提交到 Git 的环境变量里；接下来 2 分钟配 Claude Code 的 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL；再用 2 分钟写项目级 .mcp.json；然后用 2 分钟启动 Claude Code，用 claude mcp list 和会话里的 /mcp 确认 filesystem server 已连接；最后 2 分钟发一条只读检索 Prompt，看工具调用是否真的发生。

这个切法有个前提：你不在生产机、不在生产仓库上做实验。准备一个专门用来测试的 Git 仓库，里面放几个 Markdown、JSON、TS 或 Python 文件就够了。filesystem MCP Server 支持多个授权目录，但第一次跑通只要给一个目录，路径越窄越安全。把 /、用户主目录、公司共享盘整个塞进去，看起来很爽，后面出问题很难定位，也不符合最小权限原则。

1.2 filesystem MCP Server 的最小能力边界

filesystem MCP Server 常见工具包括 list_allowed_directories、list_directory、directory_tree、search_files、read_text_file、read_multiple_files、get_file_info 等只读能力，也包含 write_file、edit_file、create_directory、move_file 这类写入能力。这篇只验证检索，所以 Prompt 里要明确「只读、不写、不删、不改」。工具链本身能写，不代表你第一次就要开放写权限。先把只读链路跑通，再决定要不要给写入。

最小目标可以写成三条：第一，Claude Code 能列出 filesystem server 里的 allowed directories；第二，Claude Code 能对测试仓库执行一次 search_files 或「先 list 再 read」；第三，返回结果里能看到文件路径和匹配行。只要这三条达成，filesystem MCP 就算接上了。至于写入、重命名、批量编辑，可以后面单独开一个测试目录再做。中文路径、空格路径、软链接目录在第一次配置时尽量避开，减少变量。

1.3 环境前提

先确认本机已经有 Node.js、npm、Claude Code，以及一个测试仓库的绝对路径。下面的检查命令不依赖任何模型通道，先把本地工具链确认好。版本号以你本机输出为准，本文不写具体版本，也不把版本号当评测数字。

如果 claude 命令找不到，先把 Claude Code 的安装路径修好，再继续下面步骤。如果 npm 全局目录没有写权限，npx 首次拉包可能失败，可以先在普通终端手动执行一次 filesystem server 的启动命令，确认包能下载。注意，这一步只是预热包缓存，不要把它接到生产目录，也不要拿它去读写重要文件。

2. 拿 Key 与 Claude Code 三件套：Base URL 只填 https://taotoken.net/api

注册和创建 Key 放在最前面，是因为 Claude Code 要先能连上模型，才能决定调用哪个 MCP 工具。打开 TaoToken 官网 注册，进控制台创建 API Key。Key 只在创建时完整显示一次，复制后放到本机环境变量或 ~/.claude/settings.json，不要写进 .mcp.json，更不要提交到仓库。如果你已经有一个测试 Key，也可以直接用，但建议新建一个只用于本次 MCP 实验的 Key，方便后面看用量。

Claude Code 接兼容 Anthropic 的通道时，核心是三个环境变量：ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL。Base URL 固定写 https://taotoken.net/api，末尾不带 /v1。模型 ID 从模型广场复制，以模型广场为准。不同模型在广场里的 ID 可能更新，配置里写死一个旧 ID 容易 404，所以本文的代码片段用 YOUR_MODEL_ID 占位，你复制时替换成广场里看到的正式 ID。

临时在 shell 里验证可以这样写：

export ANTHROPIC_BASE_URL="https://taotoken.net/api"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export ANTHROPIC_MODEL="YOUR_MODEL_ID"

然后跑一条最小请求，确认模型通道能通：

claude -p "只回复 OK"

如果输出 OK，说明 Key、Base URL、模型 ID 至少没有明显问题。如果报 401，先检查 ANTHROPIC_AUTH_TOKEN 是不是复制少了字符；如果报 404 或 model not found，先检查 ANTHROPIC_BASE_URL 是不是多写了 /v1，以及 ANTHROPIC_MODEL 是不是从模型广场复制的正式 ID。模型广场里的 ID 以你打开页面时看到的为准，不要凭记忆填。

长期在项目里用，可以写 ~/.claude/settings.json，把环境变量放在 env 里。这样每个终端窗口不用重复 export，也避免把 Key 写进项目文件：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://taotoken.net/api",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "YOUR_MODEL_ID"
  }
}

这里再次强调，ANTHROPIC_BASE_URL 只写 https://taotoken.net/api，不要加 UTM，不要加 /v1，不要写成对话页地址。TaoToken 在这篇里是统一入口：Claude Code 负责发模型请求，filesystem MCP Server 负责本地文件检索，两者通过 Claude Code 这个宿主串起来。Codex 的配置是另一套，~/.codex/config.toml 不要套 ANTHROPIC_* 变量；CC Switch 也是自定义供应商 + Base URL + Key + 模型 ID 的三件套逻辑。本文只跑 Claude Code，其他宿主先不混进来。

模型通道确认后，先别急着写 MCP。回到一个干净的项目目录，用 claude 进入会话，问一句「当前工作目录是什么」，让它正常回答。这个动作能排除模型通道和项目信任问题。如果 Claude Code 连普通对话都报错，先把环境变量和 settings 优先级理清楚。Claude Code 读取配置的顺序受 shell、项目设置和用户设置影响，最稳的验证方式是开一个新终端，重新 export 三个变量，再跑一次 claude -p "只回复 OK"。

3. 把 filesystem MCP Server 挂进 Claude Code

Claude Code 支持项目级 MCP 配置，最小可复制方式是项目根目录放一个 .mcp.json。这个文件描述要启动哪个 MCP Server、用什么命令、授权哪些目录。filesystem server 用 npx 启动，参数里给绝对路径。路径不要写 ./repo、../repo 这种相对路径，因为 Claude Code 启动 MCP 进程时的工作目录不一定和你当前 shell 一样。写成绝对路径，排障时少一半猜测。

下面是最小配置片段，把 /ABSOLUTE/PATH/TO/YOUR/REPO 换成你的测试仓库绝对路径：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/ABSOLUTE/PATH/TO/YOUR/REPO"
      ]
    }
  }
}

如果测试仓库路径里有空格，JSON 字符串里正常写空格即可，args 数组会把它当成一个参数。如果想让 filesystem server 同时访问两个目录，在 args 最后继续追加绝对路径。第一次只给一个目录。配置保存后，Claude Code 在项目里启动时会读取 .mcp.json，并询问是否信任这个项目的 MCP 配置。选择信任后，server 才会真正启动。这个信任提示是 Claude Code 的安全边界，不要为了省事把整个主目录加进去。

也可以用 claude mcp add 命令添加，效果和写 .mcp.json 类似，但作用域和写入位置取决于你用的参数：

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /ABSOLUTE/PATH/TO/YOUR/REPO

添加后查看列表：

claude mcp list

你可能会看到类似下面的输出，字段名和符号以你本机 Claude Code 版本为准：

filesystem: npx -y @modelcontextprotocol/server-filesystem /ABSOLUTE/PATH/TO/YOUR/REPO - connected

如果显示未连接，先在普通终端手动跑同样命令：

npx -y @modelcontextprotocol/server-filesystem /ABSOLUTE/PATH/TO/YOUR/REPO

这个命令会启动一个 stdio MCP Server，终端看起来像「卡住」是正常的，因为它等你输入 JSON-RPC 消息。按 Ctrl+C 退出即可。能启动说明包下载和路径没问题，问题更可能在 Claude Code 的 MCP 配置作用域或信任状态。进入 Claude Code 会话后，输入 /mcp 可以查看当前会话加载了哪些 server。列表里出现 filesystem，并且状态可用，就可以进入下一步检索。

这一章常见的错有三个。第一，.mcp.json 放错位置。项目级配置要放在你启动 Claude Code 的项目根目录，不要在子目录里启动却把配置放在父目录。第二，路径不存在。MCP Server 启动时不会帮你创建目录，路径写错就直接失败。第三，npx 首次下载超时。可以提前手动执行一次启动命令，把包缓存下来。把这三个点检查完，再去看协议层，通常没必要。

4. 完成一次仓库文件检索：从 Prompt 到工具调用

模型通道和 MCP 通道都通了以后，检索本身很简单。进入测试仓库，启动 Claude Code，发一条边界清楚的 Prompt。重点不是让模型「随便看看」，而是让它调用 filesystem server 的检索工具，并返回可验证的路径和行号。Prompt 里要明确只读，避免它调用 write_file、edit_file 这类工具。下面这条可以直接改路径后使用：

只读检索。请在 /ABSOLUTE/PATH/TO/YOUR/REPO 里查找所有 Markdown 文件中包含 "mcp" 的行，返回文件路径、行号和匹配内容。不要写入、不要修改、不要删除任何文件。

Claude Code 通常会先调用 filesystem 的 search_files，或者在文件类型过滤不够时先 list_directory 再 read_text_file。你会在会话里看到工具调用卡片，类似下面这种结构。具体字段名以你本机版本为准，这里只展示验证点：

● filesystem:search_files
  path: "/ABSOLUTE/PATH/TO/YOUR/REPO"
  pattern: "mcp"
  include: "*.md"

返回结果里应该出现文件路径和匹配行。如果仓库里没有包含 mcp 的 Markdown，换一个词，比如 README、config、import，或者直接把 pattern 改成你仓库里确定存在的字符串。验证标准不是输出多漂亮，而是你能在结果里看到三样东西：server 名是 filesystem，工具名是文件检索类工具，路径落在你授权的测试目录内。三样都满足，就说明 Claude Code 通过 MCP 读到了仓库文件。

4.1 检索 Prompt 模板

只读检索的 Prompt 可以固定成模板，把仓库路径、关键词、文件类型三个变量留出来。这样每次复现只用改参数，不用重新想表达。模板里加一句「先返回匹配路径列表，不要一次性读取全部文件内容」，能减少上下文膨胀。filesystem MCP 的工具结果会进入模型上下文，search_files 返回太多行，或者 read_multiple_files 一次读太多文件，都会让后续回答变慢、变贵。先列路径，再按需读具体文件，是更稳的上下文策略。

只读检索任务。
仓库路径：/ABSOLUTE/PATH/TO/YOUR/REPO
关键词：mcp
文件类型：*.md
要求：
1. 只使用 filesystem MCP 的只读工具。
2. 先返回匹配文件路径列表。
3. 我确认后再读取具体文件片段，不要一次性读取全部内容。
4. 不要写入、不要修改、不要删除任何文件。

4.2 预期工具调用输出

验证输出不需要截很长。你只要确认工具调用链是 Claude Code -> filesystem MCP Server -> 本地文件，不是模型凭空编造。一个健康的输出会包含绝对路径，路径前缀和你 .mcp.json 里授权的目录一致。如果路径出现在授权目录之外，说明 server 的 allowed directories 配错了，或者你配置了多个目录但没意识到。发现越界路径，立刻停掉，检查 .mcp.json。

> 只读检索 /ABSOLUTE/PATH/TO/YOUR/REPO 下 *.md 中包含 mcp 的行

● filesystem:search_files
  pattern: "mcp"
  path: "/ABSOLUTE/PATH/TO/YOUR/REPO"
  include: "*.md"

找到 2 个文件：
- /ABSOLUTE/PATH/TO/YOUR/REPO/README.md:12: MCP 配置说明
- /ABSOLUTE/PATH/TO/YOUR/REPO/docs/mcp.md:3: filesystem MCP Server

4.3 只读边界与生产库隔离

filesystem MCP Server 的能力不止读，还有写。你在配置里给了哪个目录，Claude Code 在得到模型工具调用后，就有可能在那个目录里执行写操作。第一次跑通时，Prompt 写「只读」只是软约束，不是硬隔离。硬隔离靠 .mcp.json 里的路径：只给测试仓库，不给生产仓库；只给一个子目录，不给整个主目录。生产库和生产机不要直接接进 MCP。如果确实要改生产数据，让 AI 生成命令或 SQL，你本地审阅、本地执行，再把结果贴回对话。AI 工具不能直接替你执行生产业务。

4.4 结果太多怎么收敛

检索结果太多时，先缩小 pattern，再加 include 过滤，最后才考虑读文件。例如把 mcp 换成 mcpServers，把 *.md 换成 docs/*.md，或者先查 list_allowed_directories 确认授权根目录。不要一上来让 Claude Code 读 directory_tree 全量输出，目录树在大型仓库里会非常长，直接塞爆上下文。filesystem server 的 search_files 更像本地 grep，适合先定位；read_text_file 适合按行读片段。把检索和精读拆成两轮，Token 花得更值。

5. 排障与复现：本篇配置错之外不展开

排障时先把模型通道和 MCP 通道分开。模型通道看 claude -p "只回复 OK"，MCP 通道看 claude mcp list 和 /mcp。两边都通，再看 Prompt 和仓库内容。下面这张表只覆盖本篇配置里最容易错的点，不展开其他宿主、其他协议、其他插件的排障。

复现这张表时，环境尽量保持一致：同一把 TaoToken Key、同一个 Base URL、同一个模型 ID、同一个测试仓库、同一条 Prompt。本文不含排行分数，也不把一次工具调用输出当成公榜成绩。你跑出来的结果只代表你本机这次配置。换机器、换网络、换模型，输出都可能不同。真正要确认的是链路：模型通道有没有通，MCP Server 有没有启动，文件检索有没有落在授权目录里。

如果模型通道正常但 MCP 没加载，优先看项目级 .mcp.json 的信任状态。Claude Code 对项目级 MCP 有安全确认，未确认时不会自动启动 server。如果 MCP 加载了但检索失败，先手动运行 npx -y @modelcontextprotocol/server-filesystem /你的/测试仓库，确认包能启动，再回到 Claude Code 里看工具调用卡片。排障顺序别反过来：先本地进程，再宿主配置，最后才怀疑模型。模型通道用 TaoToken 的 Key 和 Base URL 接上后，它只负责生成工具调用意图，不负责执行本地文件搜索。

跑完这次检索，打开 模型对话 确认这次调用是否入账；长期开发可以看 Coding Plan。Key 在 控制台 创建；Claude Code 三件套和 MCP 配置可以对照 接入文档。先跑通只读检索，再考虑要不要开放写入。

🚀 告别海外账号与网络限制！稳定直连全球优质大模型，限时半价接入中。 👉 点击领取海量免费额度