1. 项目概述为AI助手装上本地日语词典引擎如果你正在学习日语或者像我一样需要频繁地查阅日语词汇和汉字那么你肯定对浏览器插件Yomitan不陌生。它是一个强大的日语词典聚合工具能让你在浏览网页时随时划词查询。但它的能力远不止于此——通过其内置的API我们可以将这本“本地词典”的能力开放给任何程序。今天要聊的这个项目yomitan-mcp-server就做了一件非常酷的事它把Yomitan变成了一个标准的MCP服务器。MCP全称是Model Context Protocol你可以把它理解为一套“插件标准”。它让像Claude Desktop、Cursor、OpenClaw这类AI助手或智能编辑器能够安全、规范地调用外部工具和服务。简单来说这个项目就是一座桥桥的一头是你电脑本地、离线运行的Yomitan词典数据库另一头则是你日常使用的AI工作伙伴。从此你在和AI讨论日语问题时它不再需要依靠可能过时、不准确或需要联网的在线词典而是能直接、实时地查询你精心维护的本地词库甚至能帮你一键生成Anki卡片。我最初发现这个需求是因为在用Claude辅助阅读日语技术文档时经常需要手动复制生词去查来回切换非常打断思路。而yomitan-mcp-server彻底解决了这个问题。它的核心价值在于三个关键词离线、即时、无缝。所有查询都在本地完成没有隐私泄露风险响应速度取决于你的本地API几乎是瞬间的最重要的是它深度集成到了你的AI工作流中查询动作变得像呼吸一样自然。2. 核心原理与架构设计解析2.1 MCP协议AI的“外挂”标准要理解这个项目首先得弄明白MCP是什么。它不是某个具体的软件而是一个由Anthropic主导设计的开放协议。你可以把它类比为电脑的USB接口标准。在USB标准出现之前每个外设鼠标、键盘、打印机都需要专门的驱动和接口混乱不堪。MCP的出现就是为了给AI智能体Agent提供一个统一的“USB接口”。一个MCP服务器比如我们这个yomitan-mcp-server就是一个标准的“外设”。它向MCP客户端如Claude Desktop宣告“嗨我这里有这几个工具Tools可以用lookup查单词、kanji查汉字……” 客户端收到这个清单后就能在合适的时机按照协议规定好的格式向服务器发送请求。服务器处理完比如查询了本地Yomitan数据库再把结果以标准格式返回。整个过程客户端不需要知道Yomitan的API细节服务器也不需要知道对面是Claude还是Cursor它们只认MCP这个“普通话”。这种设计带来了巨大的灵活性。对于开发者来说只要按照MCP协议实现一个服务器它的功能就能被所有兼容MCP的客户端使用。对于用户来说你可以在不同的AI工具间无缝切换你为Yomitan配置的词典、Anki模板在任何地方都有一致的体验。2.2 Yomitan API本地词典能力的基石项目的另一端是Yomitan扩展本身提供的HTTP API。Yomitan在启用“本地消息传递”功能后会在你的电脑本地通常是127.0.0.1:19633启动一个微型的HTTP服务器。这个服务器暴露了一系列端点比如/api/v1/query用于查询词汇/api/v1/parse用于解析句子。yomitan-mcp-server的核心工作就是充当一个“翻译官”和“调度员”。它内部实现了MCP服务器所需的协议逻辑当收到一个MCP格式的lookup请求时它会将这个请求“翻译”成Yomitan API能理解的HTTP请求发送给本地的19633端口。拿到Yomitan返回的原始数据通常是包含多个词典结果的JSON后它再对其进行过滤、重组和格式化转换成MCP客户端期望的结构最后返回。这里有一个关键的设计考量数据转换与优化。Yomitan API返回的数据非常详尽包含了来自所有已启用词典的原始信息这对于浏览器插件显示是完美的。但对于AI的上下文Context来说过于冗杂的信息反而会成为干扰。因此这个MCP服务器在lookup工具中做了优化处理它会提取最核心的定义、读音和标签以更紧凑、更适合AI消化理解的格式返回。这体现了开发者对实际应用场景的深刻理解——不是简单的中转而是有意义的加工。2.3 工具集设计围绕学习工作流的深度集成项目提供的6个工具不是随意堆砌的它们构成了一个完整的日语学习辅助工作流闭环基础查询 (lookup,kanji,tokenize): 这是核心的词典功能。lookup解决“这个词什么意思”kanji解决“这个字怎么读、怎么写、有什么含义”tokenize则更高级它能将整个句子分解成有意义的词汇和语法单位并附上查询结果。这对于AI理解一个复杂日语句子的结构至关重要。状态检查 (status): 这是一个保障性工具。在开始任何操作前或者遇到问题时先用它检查到Yomitan后端的连接是否正常、版本是否兼容。这避免了在工具链故障时进行盲目的调试。Anki集成 (anki_discover,anki_fields): 这是将“学习”转化为“记忆”的关键一步。很多用户包括我使用Yomitan的一大动力就是其强大的Anki制卡功能。这两个工具将这个功能从浏览器扩展中“提取”出来赋予了AI。anki_discoverv1.2.0新增是一个“侦察兵”。由于每个用户的Anki笔记类型和Yomitan字段映射配置都可能不同直接让AI生成字段内容可能会因为字段名不匹配而失败。这个工具会主动探测你当前Yomitan配置中所有可用的字段标记如{expression},{glossary},{single-glossary-大辞林}并返回一个列表。这是一个极其重要的实用设计它解决了配置动态性的问题让自动化流程变得健壮。anki_fields则是“生成器”。在知道了可用的字段标记后AI就可以针对一个查询到的词汇调用此工具生成一个已经填充好内容的字段字典。用户或后续脚本可以直接将这个字典用于创建Anki卡片。这个工具集的设计清晰地反映了从“查询理解”到“知识内化”的完整路径使得AI不仅能回答关于日语的问题还能直接参与到你的记忆过程中成为一个真正的学习伙伴。3. 详细配置与实操指南3.1 环境准备确保基石稳固在架设这座“桥”之前必须确保两端的基石都稳固Yomitan扩展和Node.js环境。Yomitan扩展配置重中之重:安装与基础设置: 从Chrome网上应用店或Firefox插件商店安装Yomitan。完成基础安装后你需要导入至少一部词典文件.yomitan格式。没有本地词典数据库一切功能都是无源之水。建议初学者从EPWING格式的经典词典如大辞林、明镜国语转换开始或使用社区分享的词典包。启用本地消息传递: 这是Yomitan与外部程序通信的基础。打开Yomitan的设置页面。找到“高级”选项卡。勾选“启用本地消息传递”。这一步通常会在你的系统上安装一个小的本地程序允许浏览器扩展与本地脚本通信。启用并配置Yomitan API:在“高级”选项卡中继续找到“Yomitan API”部分。将开关设置为“启用”。确认服务器URL为http://127.0.0.1:19633默认值通常无需改动。关键点确保你使用的地址和后续MCP服务器配置中要连接的地址一致。127.0.0.1和localhost在绝大多数情况下是等价的但某些特殊的网络配置或防火墙规则下可能有区别统一使用127.0.0.1是最稳妥的。注意完成上述设置后务必保持浏览器运行并且Yomitan扩展处于激活状态。Yomitan API服务器是随着浏览器扩展进程启动的关闭浏览器会导致连接中断。如果你习惯用完就关浏览器需要调整这个习惯或者让浏览器在后台最小化运行。Node.js环境准备:项目使用Node.js运行这带来了极大的便利性。你不需要克隆代码库或进行复杂的构建。访问Node.js官网下载并安装LTS版本如v18.x或v20.x。安装过程通常很简单一路下一步即可。打开终端Windows上的CMD/PowerShellmacOS/Linux上的Terminal输入node --version和npm --version确认安装成功并显示版本号。无需全局安装任何包。项目通过npx运行这是一个随Node.js附带的工具可以临时下载并执行npm包中的命令用完后会自动清理保持系统环境干净。3.2 客户端配置以Claude Desktop为例不同的MCP客户端配置方式类似核心都是在一个配置文件中声明要使用的MCP服务器。这里以目前用户群可能最大的Claude Desktop为例。定位配置文件:macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在手动创建即可。编辑配置文件: 用任何文本编辑器如VS Code、Notepad打开这个JSON文件。初始内容可能是一个空对象{}或者已经有其他配置。我们需要在其中添加mcpServers部分。{ mcpServers: { yomitan-mcp: { command: npx, args: [ -y, yomitan-mcp-serverlatest ] } } }yomitan-mcp: 这是你给这个服务器起的名字可以自定义但建议保持清晰。command: npx: 指定运行命令为npx。args: 传递给npx的参数。-y: 这是npx的参数表示对所有提示自动回答“yes”避免安装过程中出现交互式确认导致进程挂起。yomitan-mcp-serverlatest: 指定要运行的npm包名及其版本latest表示最新稳定版。重启客户端: 保存配置文件后完全退出并重新启动Claude Desktop。这是必须的步骤因为MCP服务器配置只在启动时被读取。验证连接: 重启后当你新建一个对话时如果配置正确Claude的界面上通常会出现一个微小的提示或者你可以在输入框附近看到新工具的图标不同客户端表现不同。最直接的验证方法是在对话中尝试让Claude使用Yomitan。例如你可以输入“请用Yomitan查一下「継続は力なり」这个谚语的意思。”如果Claude回应说它无法找到或调用该工具说明配置可能未生效。请再次检查配置文件路径是否正确、JSON格式是否有效可以使用在线JSON校验工具并确认已重启客户端。3.3 Anki集成配置详解Anki集成是提升学习效率的利器但需要Yomitan和Anki两端都做好配置。第一步在Yomitan中配置Anki连接打开Yomitan设置进入“Anki”选项卡。点击“配置Anki卡片格式...”。这里是你设计卡片模板的地方。在“笔记类型”中选择或创建一个用于日语词汇的笔记类型如“Japanese Vocabulary”。在“字段映射”中将Yomitan提供的变量标记映射到Anki笔记的具体字段上。这是最关键的一步。常见的映射包括{expression}- 单词字段如“Expression”{reading}- 读音字段如“Reading”{glossary}- 释义字段如“Meaning”{sentence}- 例句字段你还可以使用词典特定的标记如{single-glossary-大辞林}这样释义就只来自《大辞林》这一部词典保证风格统一。配置好后最好在浏览器里用Yomitan的“添加到Anki”功能手动测试一次确保卡片能按预期生成。第二步在AI会话中使用集成工具当Yomitan-Anki链路打通后你可以在AI对话中这样高效地工作侦察阶段: 首先你可以让AI调用anki_discover工具。它会返回一个列表告诉你当前配置下所有可用的字段标记。例如你可能会看到[expression, reading, glossary, single-glossary-大辞林, sentence]。把这个列表记下来或告诉AI。查询与生成阶段: 当你遇到一个生词比如“曖昧”让AI先调用lookup工具查询其含义和读音。然后基于查询结果和刚才anki_discover得到的字段列表让AI调用anki_fields工具指定单词为“曖昧”。AI会返回一个JSON对象例如{ expression: 曖昧, reading: あいまい, glossary: 【形動】1. はっきりしないさま。明確でないさま。2. 態度や考えがどっちつかずではっきりしないさま。, single-glossary-大辞林: はっきりしないこと。また、そのさま。 }制卡阶段: 现在你手中就有了一个已经格式化好的数据块。你可以手动复制这些内容到Anki或者利用Anki的API通过AnkiConnect插件编写一个简单的脚本让AI建议的后续步骤自动完成卡片创建。这就实现了从“遇到生词”到“生成记忆卡片”的半自动化甚至全自动化流水线。4. 实战应用场景与技巧4.1 场景一沉浸式阅读与技术文档翻译作为一名开发者我经常需要阅读日语的技术博客、API文档或开源项目的Issue。以前我需要频繁切换窗口在浏览器和词典软件之间来回跳转。现在我的工作流是这样的打开Claude Desktop新建一个对话。将日语文档的复杂段落或包含陌生术语的句子复制给Claude。提示它“请调用tokenize工具分析这个句子并对其中我不认识的词汇特别是IT相关术语用lookup工具详细查询。”Claude会返回句子的结构分析并将生词及其在技术语境下的释义清晰地列出来。我甚至可以要求它“将lookup查询到的这个术语的解释用中文重新组织成更易懂的技术说明。”实操心得对于长句tokenize工具比手动拆分单词更可靠因为它能准确处理日语中复杂的黏着语结构和复合词。在技术领域很多术语在通用词典中释义不佳此时Yomitan中导入的IT专业词典或网络词典如weblio就能发挥巨大作用。你可以指导AI优先参考特定词典的结果。4.2 场景二写作辅助与表达校验在尝试用日语写邮件、技术评论或社交媒体内容时对用词和语法缺乏自信。新的工作流用日语起草好一段文字。发给Claude并提示“请检查这段日语的表达是否自然。对其中你觉得可能不地道或存在歧义的词汇使用lookup工具核实其用法和常见搭配。”Claude不仅能指出问题还能基于Yomitan返回的词典信息通常会包含例句和用法说明提供修改建议。例如它可能会说“‘検討する’在这里使用是正式的但结合上下文使用‘考えてみる’会更口语化、更自然。根据词典后者常用于表示‘尝试考虑一下’。”注意事项AI的判断基于词典的静态信息而语言是鲜活的。对于最新的网络用语或非常特定的领域黑话词典可能覆盖不到。此时应将AI的建议作为重要参考而非绝对标准。对于非常重要的文书最终仍需人工复核或请教母语者。4.3 场景三系统性词汇学习与卡片管理这是我个人最常用的场景将偶然的查询转化为系统的记忆。主题式学习例如我想学习与“编程”相关的日语词汇。我会让Claude帮我生成一个列表比如“变量、函数、循环、条件分支、调试、仓库、提交……”然后我们开启一个循环AI调用lookup查询一个词。我们讨论其释义特别是与中文或英文术语的细微差别。AI调用anki_fields生成该词的卡片数据。我将数据暂存或批量处理。 一个会话下来就能高效地构建一个主题明确的Anki牌组。例句挖掘在查询一个单词时Yomitan的某些词典如“大辞林”或“新明解”会提供经典的例句。这些例句是学习单词用法的黄金材料。我会让AI在返回查询结果时特意提取出例句部分。然后我可以将这些例句单独做成卡片填空卡或句卡或者附在单词卡后面加深理解。高级技巧利用Anki的“自定义笔记类型”功能你可以在Yomitan的字段映射中创建一些自己定义的字段比如“记忆技巧”、“联想词”、“近义词辨析”。然后在AI生成anki_fields后你可以手动或在AI的帮助下向这些自定义字段补充内容。这样生成的卡片就融合了权威词典的释义和你个人的学习痕迹记忆效果远超简单的词义罗列。5. 故障排查与常见问题实录即使按照指南操作也难免会遇到问题。下面是我在部署和使用过程中遇到的一些典型情况及解决方法。5.1 连接类问题问题AI客户端报告无法连接到Yomitan MCP服务器或调用工具时超时/失败。排查步骤1检查Yomitan API服务状态这是最常见的问题根源。首先在浏览器中访问http://127.0.0.1:19633/。如果Yomitan API正常运行你会看到一个简单的文本响应如“Yomitan API”。如果无法访问连接被拒绝说明API服务未启动。解决确认浏览器正在运行且Yomitan扩展已启用。然后进入Yomitan设置 - 高级确认“Yomitan API”开关已打开。有时需要关闭再重新打开一次这个开关。排查步骤2验证MCP服务器进程当AI客户端启动时它会尝试运行你在配置中指定的命令npx -y yomitan-mcp-serverlatest。你可以通过系统任务管理器Activity Monitor, Task Manager查看是否有Node.js进程在运行。如果没有说明客户端启动MCP服务器失败。解决检查配置文件claude_desktop_config.json的JSON语法是否正确特别是逗号和括号。尝试在终端中手动运行命令npx -y yomitan-mcp-serverlatest看是否有错误输出。常见的错误是Node.js版本过低请确保使用v18或更高版本。排查步骤3防火墙或安全软件拦截极少情况下本地回环地址127.0.0.1的特定端口通信会被安全软件误拦截。解决暂时禁用防火墙或安全软件进行测试。如果问题消失则需要在安全软件中为Node.js或Claude Desktop添加允许规则。5.2 功能类问题问题lookup或kanji工具能工作但anki_fields工具返回HTTP 500错误。原因分析HTTP 500是服务器内部错误。对于anki_fields这几乎总是因为传递给Yomitan API的字段标记marker名称与当前配置不匹配。标准解决流程不要猜测立即使用anki_discover工具。让AI调用它获取当前Yomitan配置中实际有效的字段标记列表。核对将你期望使用的字段名如glossary与anki_discover返回的列表进行比对。你会发现可能你配置的字段名是meaning或者你使用了词典特定的标记如single-glossary-大辞林而anki_fields调用时却用了通用的glossary。修正在后续调用anki_fields时严格使用anki_discover返回的标记名。例如如果列表里只有single-glossary-大辞林那么你就应该用这个全名。问题查询结果不准确或缺少期望的词典释义。原因分析Yomitan MCP服务器本身不存储词典它只是转发查询。结果取决于你本地Yomitan中安装并启用了哪些词典以及这些词典的质量。解决打开Yomitan扩展的词典管理界面确认你需要的词典如“大辞林”、“明镜”、“weblio”已启用。在Yomitan的设置中可以调整词典的查询顺序。排在前面的词典会优先返回结果。如果你希望某个词典的结果出现在AI返回内容的前列可以将其顺序提前。理解lookup工具的优化逻辑。它可能不会返回所有词典的所有内容而是做了精简。如果需要更原始的数据你可能需要直接研究Yomitan的原始HTTP API但这超出了本MCP服务器的范畴。5.3 性能与优化建议响应延迟如果感觉查询变慢首先检查是否在Yomitan中启用了过多词典。每次查询都会遍历所有启用词典词典数量过多会影响速度。建议只启用你真正需要的高质量词典。AI上下文管理频繁调用lookup并让AI将大段释义写入对话历史会快速消耗AI模型的上下文窗口。对于长文阅读可以策略性地让AI只查询关键术语或对释义进行总结性转述而不是全文照搬。命令的稳定性在配置中我们使用了latest标签来获取最新版。这通常没问题但极少数情况下新版本可能存在临时性bug。如果你遇到突然出现的问题且排除了自身配置原因可以尝试在配置中指定一个已知稳定的旧版本号例如yomitan-mcp-server1.2.0以暂时规避问题。这个项目将本地化、隐私优先的日语词典能力与现代化的AI助手工作流优雅地结合了起来。它没有改变Yomitan和Anki这些经典工具的核心而是通过MCP这个标准化的“插槽”让它们的能力在新时代的AI交互场景中焕发了新生。对我而言它最大的价值不是替代了某个步骤而是消除了工具间的摩擦让查询、理解、记忆这个学习循环变得无比顺畅。如果你已经在使用Yomitan和Anki那么花上半小时配置这个MCP服务器绝对是一项高回报的投资。