Local-only MCP server exposing fast code navigation, reading, and editing tools over STDIO.
npm install code-tools-mcpCode Tools MCP Server
- Local-only MCP server exposing core coding tools for LLMs via STDIO.
- Tools: list_directory, read_file, write_file, grep, ripgrep, glob, edit, read_many_files.
Codex CLI on windows sort of sucks because it relies on writing PS / Python scripts for basic read, write, grep operations. This MCP server exposes those standard tools making Codex CLI faster on Windows. You can use it on Linux or Mac, it will work but may not be necessary.
This is without warranty, any issues or bugs should be reported to the repository but be aware of the risks and use it at your own risk.
Install
- Global: npm i -g code-tools-mcp
- One-off: npx code-tools-mcp
Run
- code-tools-mcp --root C:/path/to/workspace
CODEX CLI Config Example
```
[mcp_servers.code-tools]
command = "{path to npm.cmd}"
args = [ "-y", "code-tools-mcp"]
env = { APPDATA = "C:\\Users\\{username}\\AppData\\Roaming", LOCALAPPDATA = "C:\\Users\\{username}\\AppData\\Local", HOME = "C:\\Users\\{username}", SystemRoot = "C:\\Windows", ComSpec = "C:\\Windows\\System32\\cmd.exe" }
startup_timeout_ms = 20_000
Workspace root is auto-detected:
- If CODE_TOOLS_MCP_ROOT is set, it wins.--root C:/path/to/workspace
- Else if a CLI flag is passed, it’s used: (or -r)..git
- Else, the server looks upward from the current working directory for a folder and uses that directory as root.
- Else, it defaults to the current working directory.
Claude config example without env var (pass a root flag):
``
{
"mcpServers": {
"code-tools": {
"command": "node",
"args": [
"C:/Users/adity/Projects/code-tools-mcp/dist/index.js",
"--root",
"C:/Users/adity/Projects/code-tools-mcp"
]
}
}
}
Claude Desktop Config Example
Add to your Claude config JSON:
``
{
"mcpServers": {
"code-tools": {
"command": "node",
"args": ["/ABSOLUTE/PATH/code-tools-mcp/dist/index.js"],
"env": { "CODE_TOOLS_MCP_ROOT": "/ABSOLUTE/PATH/TO/YOUR/WORKSPACE" }
}
}
}
Notes
- Uses STDIO transport; avoid console.log (stdout). Any diagnostics are written to stderr.read_file
- File operations are restricted to the workspace root.
- caps file size at 2MB; search ignores common large folders..gitignore
- Only patterns are respected (.geminiignore is NOT supported).
---
---
.Parameters:
-
path (string, required): Absolute path to directory
- ignore (string[], optional): Glob patterns to ignore
- file_filtering_options (object, optional): { respect_git_ignore?: boolean }Example:
`typescript
await client.callTool('list_directory', {
path: '/path/to/workspace/src'
});
`$3
Reads a file with optional pagination. Binary-aware.Parameters:
-
absolute_path (string, required): Absolute path to file
- offset (number, optional): Starting line (0-based)
- limit (number, optional): Number of lines to return (max 2000)
- allow_ignored (boolean, optional): Allow reading .gitignore-ignored files (default: false)Features:
- Returns
nextOffset in structured content for paginated reads
- Includes summary with line count in all responsesExample:
`typescript
await client.callTool('read_file', {
absolute_path: '/path/to/workspace/src/index.ts',
offset: 0,
limit: 100
});
`$3
Creates or overwrites a file with preview mode.Parameters:
-
file_path (string, required): Absolute path of file to write
- content (string, required): Full file content
- apply (boolean, default: false): If false, returns diff preview without writing
- overwrite (boolean, default: true): Allow overwriting existing filesFeatures:
- Preview mode by default (set
apply: true to write)
- Returns diff in structured contentExample:
`typescript
await client.callTool('write_file', {
file_path: '/path/to/workspace/src/new-file.ts',
content: 'export const foo = "bar";',
apply: true
});
`$3
Text/regex search with smart-case support.Parameters:
-
pattern (string, required): Search pattern (plain text or regex if regex: true)
- path (string, optional): Directory path relative to workspace
- include (string, optional): Glob filter (e.g., */.{ts,tsx})
- exclude (string | string[], optional): Glob exclusion patterns
- regex (boolean, default: false): Treat pattern as regex
- ignore_case (boolean, optional): Case-insensitive search. If undefined, uses smart-case (case-sensitive if pattern has uppercase)
- max_matches (number, default: 2000): Maximum matches to returnFeatures:
- Smart-case: automatically case-sensitive if pattern contains uppercase letters
- Skips binary files
- Respects
.gitignore
- Returns truncated: true if max_matches reachedExample:
`typescript
await client.callTool('grep', {
pattern: 'function.*async',
regex: true,
include: '*/.ts',
max_matches: 100
});
`$3
Fast regex search using ripgrep binary (falls back to grep if unavailable).Parameters:
-
pattern (string, required): Regular expression
- path (string, optional): Directory to search
- include (string | string[], optional): Glob include patterns
- exclude (string | string[], optional): Glob exclude patterns
- ignore_case (boolean, optional): If undefined, uses --smart-case
- max_matches (number, default: 20000): Maximum matches to returnFeatures:
- Uses
--smart-case by default when ignore_case not specified
- Returns truncated: true if max_matches reached
- Falls back to JavaScript grep if ripgrep unavailable
- Captures stderr in structuredContent.stderrExample:
`typescript
await client.callTool('ripgrep', {
pattern: 'TODO|FIXME',
include: ['/.ts', '/.tsx'],
exclude: '/node_modules/'
});
`$3
Matches files by glob pattern with two-tier sorting.Parameters:
-
pattern (string, required): Glob pattern (e.g., */.ts)
- path (string, optional): Directory to search (defaults to workspace root)
- case_sensitive (boolean, default: false): Case-sensitive matching
- respect_git_ignore (boolean, default: true): Respect .gitignoreFeatures:
- Two-tier sorting: recent files (< 24h) newest-first, then older files alphabetically
- Reports
gitIgnoredCount when no files foundExample:
`typescript
await client.callTool('glob', {
pattern: '*/.{ts,tsx}',
path: '/path/to/workspace/src'
});
`$3
Targeted text replacement with preview mode.Parameters:
-
file_path (string, required): Absolute path to file
- old_string (string, required): Text to replace (empty string creates new file)
- new_string (string, required): Replacement text
- expected_replacements (number, default: 1): Expected number of replacements
- apply (boolean, default: false): If false, returns diff previewFeatures:
- Preview mode by default
- Detects no-change edits
- Returns
occurrences in structured contentExample:
`typescript
await client.callTool('edit', {
file_path: '/path/to/workspace/src/index.ts',
old_string: 'const foo = "old";',
new_string: 'const foo = "new";',
apply: true
});
`$3
Reads multiple files by glob patterns, concatenated output.Parameters:
-
paths (string[], required): Array of file/directory globs
- include (string[], optional): Additional glob patterns to include
- exclude (string[], optional): Glob patterns to exclude
- useDefaultExcludes (boolean, default: true): Apply default excludes (node_modules, dist, .git, etc.)
- file_filtering_options (object, optional): { respect_git_ignore?: boolean }Features:
- 2MB total output cap
- Workspace containment re-check for safety
- Aggregated skip reasons in structured content (
skipCounts)
- Returns truncated: true when total cap reachedExample:
`typescript
await client.callTool('read_many_files', {
paths: ['src/*/.ts'],
exclude: ['*/.test.ts']
});
`---
Using These Tools from an MCP Client
> Tool discovery: clients call
tools/list (supports cursor pagination) and may receive tools/list_changed when the set changes.$3
`typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';// Connect to the server
const transport = new StdioClientTransport({
command: 'node',
args: ['/path/to/code-tools-mcp/dist/index.js'],
env: { CODE_TOOLS_MCP_ROOT: '/path/to/workspace' }
});
const client = new Client({
name: 'example-client',
version: '1.0.0'
}, {
capabilities: {}
});
await client.connect(transport);
// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.tools.map(t => t.name));
// Call a tool
const result = await client.callTool({
name: 'read_file',
arguments: {
absolute_path: '/path/to/workspace/src/index.ts'
}
});
console.log('Result:', result);
`$3
`typescript
// Read large file in chunks
let offset = 0;
const limit = 100;while (true) {
const result = await client.callTool({
name: 'read_file',
arguments: {
absolute_path: '/path/to/large-file.ts',
offset,
limit
}
});
console.log(result.content[0].text);
// Check if there's more to read
const nextOffset = result.structuredContent?.nextOffset;
if (!nextOffset) break;
offset = nextOffset;
}
`---
Tool Stability
- Tool names are stable and will not change in minor versions
- Parameter names are stable - new optional parameters may be added
- Descriptions are concise - detailed parameter docs are in JSON Schema (via Zod
.describe())
- Structured content includes summary field for all tools where applicable
- Defaults and limits are documented in parameter descriptions:
- read_file: 2MB file cap, 2000 line limit per request
- read_many_files: 2MB total output cap, 1MB per file
- grep: 2000 matches default, configurable via max_matches
- ripgrep: 20000 matches default, configurable via max_matches---
TypeScript Types
All tool input and output types are available in
src/types/tools.ts:`typescript
import type {
ReadFileInput,
ReadFileStructuredOutput,
GrepInput,
GrepStructuredOutput,
// ... other types
} from 'code-tools-mcp/types/tools';
``