Allows reading Jupyter Notebook files, exposing their contents to the model while preserving the original on-disk encoding.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@encoding-bridge search for 'TODO' in the GBK source files"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Encoding-transparent file tools for Claude Code and other MCP clients.
Encoding Bridge exposes Read, Grep, Edit, and Write over MCP. It detects on-disk encodings, shows Unicode to the model, and writes files back in their original encoding.
It is designed for legacy codebases that still use GBK/GB2312/GB18030, Big5, Shift-JIS, EUC-KR, Windows codepages, UTF-16, and other non-UTF-8 encodings.
This is now the single recommended installation path for end users.
# Remove an older install with the same name first, if one exists.
claude mcp remove encoding-bridge -s user
# Register the npm package once, at user scope. `cmd` is required on Windows.
claude mcp add --scope user encoding-bridge -- cmd /d /s /c "npx -y encoding-bridge-mcp"
claude mcp get encoding-bridge# Remove an older install with the same name first, if one exists.
claude mcp remove encoding-bridge -s user
# Register the npm package once, at user scope.
claude mcp add --scope user encoding-bridge -- npx -y encoding-bridge-mcp
claude mcp get encoding-bridgeIf claude mcp get reports Connected, installation succeeded. Start a new Claude Code session. Install scripts merge permissions automatically (MCP tools allowed, built-in file tools denied). The first Read/Grep in a mixed-encoding repo builds a local encoding index in the background.
What this requires locally:
claude
node
What it does not require:
git clone
npm install
npm run build
downloading a GitHub Release package first
Register encoding-bridge in only one scope. Claude Code treats the same server name with different commands as a configuration conflict—for example, an older user-scoped local build and this repository's project-scoped .mcp.json npm command.
Run claude mcp list to diagnose duplicates. Keep the endpoint you want, then remove the other registration:
# Keep the npm command from the user-scoped installation.
claude mcp remove encoding-bridge -s project
# Or keep a project-local configuration and remove a previous user installation.
claude mcp remove encoding-bridge -s userAfter removing a registration, run claude mcp get encoding-bridge again. It must report one endpoint with status Connected.
A single-folder workspace works with zero configuration: the MCP process
cwd (the VS Code working directory) is used as the index root, so files
under it are read and indexed automatically.
In a multi-root workspace, only the first folder is the process cwd.
Encoding Bridge cannot discover the other folders by itself (VS Code does not
expose them to MCP server processes), so they must be listed explicitly via
the ENCODING_BRIDGE_ROOTS environment variable in the project .mcp.json:
{
"mcpServers": {
"encoding-bridge": {
"type": "stdio",
"command": "npx",
"args": ["-y", "encoding-bridge-mcp"],
"env": {
"ENCODING_BRIDGE_ROOTS": "C:/path/to/project-a;C:/path/to/project-b"
}
}
}
}ENCODING_BRIDGE_ROOTS is a path-separator (; on Windows, : on
Unix) delimited list of root directories. Each root gets its own
.encoding-bridge/encoding-index.json.
Files are resolved to the deepest listed root that contains them.
This file lives in the project root, so it persists across restarts — you configure it once, not on every reload.
Other users put their own paths here; the published package contains no hard-coded paths.
Read and Grep allow individual text files up to 32 MiB by default. To use a different limit, set ENCODING_BRIDGE_MAX_TEXT_FILE_MIB to a positive integer before starting Claude Code:
setx ENCODING_BRIDGE_MAX_TEXT_FILE_MIB 64Restart Claude Code after changing the variable. Larger files require proportionally more Node.js memory while decoding, splitting lines, and matching regular expressions.
Related MCP server: Code Editor MCP Server
Claude Code built-in file tools assume UTF-8 for normal text reads. In legacy projects this can lead to:
unreadable C/C++ comments and string literals;
searches that silently miss text;
edits that corrupt the original codepage;
accidental UTF-8 rewrites of GBK or other legacy files.
Encoding Bridge keeps encoding conversion below the model boundary:
legacy bytes on disk -> detect encoding -> Unicode for the LLM
Unicode from the LLM -> strict encode in the original encoding -> bytes on diskIf new text cannot be represented in the target encoding, the write fails instead of silently replacing characters with ?.
Install scripts merge Claude Code permissions automatically. Start a new session after installing. The first file tool use in a project builds a local encoding index if one does not exist yet.
claude mcp get encoding-bridgeExpected:
name: encoding-bridge
status: Connected
Examples:
Read SourceCode/Main.cpp and show the first 10 lines.Search SourceCode for the string 错误码.In a verbose / print-mode session, the tool call should be one of:
mcp__encoding-bridge__Read
mcp__encoding-bridge__Grep
mcp__encoding-bridge__Edit
mcp__encoding-bridge__Write
It should not call built-in Read, Grep, Edit, or Write.
Encoding-aware Read, Grep, Edit, and Write tools.
Automatic encoding detection and a local index built on first use.
Install scripts deny built-in file tools and allow the MCP tools.
GBK/GB2312/GB18030, Big5, Shift-JIS, EUC-KR, Windows codepages, UTF-8, and UTF-16 support.
BOM and dominant line-ending preservation for edits.
Read-before-write protection and stale-write detection.
Image, PDF, and Jupyter Notebook reading.
Grep: ASCII in one pass; non-ASCII grouped by encoding.
npm install
npm run check
npm test
npm run build
npm startMIT. See LICENSE.
Performs exact string replacements in files.
Usage:
You must use your Read tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + tab. Everything after that is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
The edit will FAIL if old_string is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
Use replace_all for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | The absolute path to the file to modify | |
| new_string | Yes | The text to replace it with (must be different from old_string) | |
| old_string | Yes | The text to replace | |
| replace_all | No | Replace all occurrences of old_string (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description covers key behavioral traits: edit will fail if old_string not unique, errors without prior read, and replace_all behavior. It could enhance by explicitly stating it's a mutation (destructive) action, but overall transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and provides detailed bullet points. While slightly lengthy, every sentence adds value. Could be tightened without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description sufficiently explains behavior and constraints (reading before editing, uniqueness failure). It addresses common pitfalls, making it complete for a string replacement tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage, but the description adds valuable context: uniqueness constraint for old_string, difference from replace_all, and emphasis on exact matching (indentation). This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Performs exact string replacements in files.' with a specific verb ('replace') and resource ('files'). It distinguishes from siblings: Grep (search), Read (read), Write (write).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: must read file before editing, preserve exact indentation, prefer editing existing files, avoid emojis, uniqueness requirement for old_string, and when to use replace_all. It also tells when not to use (e.g., avoiding unnecessary new files).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A powerful search tool for file contents.
Usage:
ALWAYS use Grep for search tasks. NEVER invoke grep or rg as a Bash command.
Supports full regular expressions, file glob filters, file type filters, context lines, match-only output, multiline matching, pagination, file lists, and per-file counts.
Use output_mode=files_with_matches when you only need file paths; this is the default.
Use output_mode=content to see matching lines. Line numbers are included by default.
Use output_mode=count to see match counts per file.
scan_mode=exact is the default: pagination never stops scanning, so counts are exact when scanComplete is true. scan_mode=fast is opt-in and only valid for files_with_matches; it stops each matching file at its first match and reports countsExact=false.
Results are limited to 250 entries by default; use head_limit and offset for pagination. Check structuredContent scanComplete, truncationReason, and outputTruncated whenever a search is resource-limited.
ASCII patterns are searched once with ripgrep and ignore file encoding.
Non-ASCII patterns (Chinese, etc.) are grouped by detected file encoding and searched with rg --encoding per group.
| Name | Required | Description | Default |
|---|---|---|---|
| -A | No | Show lines after each match | |
| -B | No | Show lines before each match | |
| -C | No | Show lines before and after each match | |
| -i | No | Case-insensitive search | |
| -n | No | Show line numbers in content mode. Defaults to true. | |
| -o | No | Print only matching non-empty parts of each line | |
| glob | No | Glob pattern used to filter files, for example *.js or **/*.ts | |
| path | No | File or directory to search. Defaults to the current working directory. | |
| type | No | File type filter such as js, ts, py, rust, go, or java | |
| offset | No | Skip the first N result lines or entries | |
| context | No | Alias for -C | |
| pattern | Yes | The regular expression pattern to search for in file contents | |
| multiline | No | Enable multiline matching where dot also matches newlines | |
| scan_mode | No | exact scans all eligible files and returns exact counts when complete. fast is opt-in for files_with_matches only and stops each matching file after its first match, so counts are not exact. | exact |
| head_limit | No | Limit returned lines or entries. Defaults to 250; 0 means unlimited. | |
| output_mode | No | Output mode. Defaults to files_with_matches. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden and delivers richly: default output mode, the 250-entry head_limit default, exact-vs-fast scan semantics and their effect on count exactness, and encoding-grouped searching for non-ASCII patterns. It also tells the agent to check structuredContent fields scanComplete, truncationReason, and outputTruncated when a search is resource-limited, which is the kind of behavioral nuance annotations would otherwise need to provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose and the key directive are front-loaded, followed by organized bullets. It is on the longer side (~330 words), and the capability-list bullet partially restates what the schema already enumerates, but nearly every sentence carries actionable information for the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 16-parameter tool with no annotations and no output schema, the description covers purpose, defaults, pagination, truncation diagnostics, and encoding edge cases exceptionally thoroughly. The remaining gap is the precise return shape of content mode and zero-match/error behavior, which an output schema would normally carry.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so every parameter is already documented in the input schema. The description adds genuine selection-level value beyond the schema by tying output_mode choices to use cases and explaining scan_mode's validity constraint and how head_limit/offset interact with the default limit, though some details (like -n defaulting to true) do duplicate schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'A powerful search tool for file contents' — a specific verb (search) and resource (file contents). The directive 'ALWAYS use Grep for search tasks' clearly differentiates it from sibling tools Read, Edit, and Write, which cover file access and modification rather than searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly commands 'ALWAYS use Grep for search tasks. NEVER invoke grep or rg as a Bash command,' giving a clear when-to-use rule and a prohibition. It also provides selection guidance for output_mode ('Use output_mode=files_with_matches when you only need file paths') and for scan_mode ('fast is opt-in and only valid for files_with_matches'), leaving little to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads a file from the local filesystem. You can access any file directly by using this tool. Assume this tool is able to read all files on the machine. If the User provides a path to a file assume that path is valid. It is okay to read a file that does not exist; an error will be returned.
Usage:
The file_path parameter must be an absolute path, not a relative path
By default, it reads up to 2000 lines starting from the beginning of the file. Files larger than 256KB will return an error; use offset and limit for larger files
When you already know which part of the file you need, only read that part. This can be important for larger files.
Results are returned using cat -n format, with line numbers starting at 1
This tool allows Claude Code to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
This tool can read PDF files (.pdf). For large PDFs (more than 10 pages), you MUST provide the pages parameter to read specific page ranges (e.g., pages: "1-5"). Reading a large PDF without the pages parameter will fail. Maximum 20 pages per request.
This tool can read Jupyter notebooks (.ipynb files) and returns all cells with their outputs, combining code, text, and visualizations.
This tool can only read files, not directories. To read a directory, use an ls command via the Bash tool.
You will regularly be asked to read screenshots. If the user provides a path to a screenshot, ALWAYS use this tool to view the file at the path. This tool will work with all temporary file paths.
If you read a file that exists but has empty contents you will receive a system reminder warning in place of file contents.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | The number of lines to read. Only provide if the file is too large to read at once. | |
| pages | No | Page range for PDF files (e.g., "1-5", "3", "10-20"). Only applicable to PDF files. Maximum 20 pages per request. | |
| offset | No | The line number to start reading from. Only provide if the file is too large to read at once | |
| file_path | Yes | The absolute path to the file to read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It comprehensively discloses behaviors: default 2000 lines, 256KB limit, cat -n output, multimodal for images, PDF pagination rules, notebook handling, directory exclusion, and empty file warning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear opening and bullet points. Every sentence serves a purpose, but the description is somewhat lengthy. Front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and no output schema, the description is remarkably complete. It covers all parameters, edge cases (empty file, directory, screenshots), and special file types (images, PDF, notebooks). No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds significant value beyond schema: file_path must be absolute, limit only for large files, pages only for PDF, offset as line number. It also provides context like defaults and error conditions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads files from the local filesystem, with specific verb and resource. It distinguishes from sibling tools (Edit, Grep, Write) by focusing solely on reading. The title and description are aligned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Extensive guidelines are provided: absolute path requirement, default line limit, file size handling, PDF and notebook specifics, and directory exclusion. However, it does not explicitly state when to use this tool over alternatives, though the sibling names imply differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes a file to the local filesystem.
Usage:
This tool will overwrite the existing file if there is one at the provided path.
If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The content to write to the file | |
| file_path | Yes | The absolute path to the file to write (must be absolute, not relative) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses overwrite behavior, the read-first requirement (and that failure occurs otherwise), and preference for Edit. Could mention directory creation or error handling, but covers key behavioral traits well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One clear introductory sentence followed by bullet points with zero redundancy. Every sentence contributes meaningful guidance. Front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but no return value explanation needed. Description covers prerequisites (read first), alternatives (Edit), and prohibitions (markdown/emojis). Complete for a file-write tool of moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. The tool description adds no additional meaning beyond the schema (e.g., no format constraints or examples). Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Writes a file to the local filesystem,' a clear verb+resource statement. It distinguishes from siblings by specifying when to use Write vs Edit (modifications) and Read (must read first for existing files).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (create new files or complete rewrites), when to avoid (prefer Edit for modifications), and prerequisites (must read file first if existing). Also includes prohibitions on markdown and emojis unless requested.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0EditGrepReadWriteScored across 4 tools
Each tool has a clear, non-overlapping purpose: Read retrieves file contents, Edit performs targeted string replacements, Write creates or overwrites files, and Grep searches file contents. There is no ambiguity in choosing which tool to use for a given task.
All tool names are single-word verbs (Read, Edit, Write, Grep) that directly describe their actions. The naming is consistent and predictable, though it does not follow a verb_noun pattern.
With 4 tools covering file reading, editing, writing, and searching, the count is well-scoped for a file manipulation server. Each tool is essential and there is no redundancy.
The tool surface covers the primary file operations (read, write, edit, search) but lacks delete, move, copy, and directory listing. These gaps are minor and can be worked around, but a file delete tool would make the set more complete.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
Read and write your Fresh Jots notes from Claude, Cursor, and any MCP client.
Persistent memory and cross-session learning for AI coding assistants (hosted remote MCP).
