Skip to content
/
Tier B A3 MCP-anchored

Claude Tools MCP Server

claude-tools-mcp · brwse/claude-tools-mcp · ★ 13 · last commit 2026-03-11

Primitive shape 9 total
MCP tools 9
00

Summary

Claude Tools MCP Server — Summary

An MCP server written in Go that exposes Claude Code's native file and shell manipulation tools (Bash, Read, Write, Edit, Glob, Grep, and variants) over HTTP, making them accessible to any MCP client remotely. The server is stateless, horizontally scalable via Docker, and uses the MCP Go SDK.

The primary use case is "remote Claude Code tools": another AI agent or system can call bash, read, write, edit, glob, grep, kill_shell, and bash_output tools over HTTP without needing Claude Code installed locally. The server also tracks file modification state and manages background shell processes.

Built by brwse (GitHub, actually a project of mathematic-inc, a 501(c)(3) non-profit). The repo has active CI/CD, a CHANGELOG, Docker support, and 13 stars. Compared to seeds: closest to ccmemory (Archetype 3 — MCP-anchored toolserver) but instead of exposing memory/knowledge graph tools, this server exposes file system and shell execution tools. It's the inverse of the batch theme — rather than converting skills to MCP tools or managing MCP servers, this creates a new MCP server that bridges Claude Code's native tools to the MCP protocol ecosystem.

01

Overview

Claude Tools MCP Server — Overview

Origin

Built by mathematic-inc (a 501(c)(3) non-profit), hosted under the brwse GitHub account. Active development as of March 2026 (most recent push). The repo description: "MCP server that exposes Claude Code's file and shell tools (bash, read, write, edit, glob, grep) over HTTP for remote use by any MCP client."

Philosophy

The server addresses the limitation that Claude Code's powerful built-in tools (especially bash with timeout/background support, edit for exact string replacement, and grep via ripgrep) are only available when running inside a Claude Code session. By exposing them as an MCP server, any MCP client can use these tools — including agents running in different environments or orchestration systems.

Key Design Principles (from CLAUDE.md and README)

  • Stateless by default: Each HTTP request handled independently, enabling horizontal scaling
  • Security first: Path validation (rejects relative paths), file size limits (10MB), output limits (~100k token max), timeout protection against slowloris attacks
  • Graceful shutdown: SIGINT/SIGTERM handling, in-flight requests complete before exit
  • File modification tracking: Detects external edits (cross-reference with Claude Code's own detection)

Tools Provided (8)

bash, bash_output, kill_shell, read, write, edit, glob, grep

These directly mirror Claude Code's own internal tool set.

Architecture Note

Uses the MCP Go SDK — the official Go implementation. The server is not affiliated with Anthropic but closely mirrors Claude Code's tool naming and behavior conventions.

02

Architecture

Claude Tools MCP Server — Architecture

Distribution

mcp-server — Go binary, Docker image, or run from source.

Install

From source:

go build -o claude-tools-mcp ./cmd/claude-tools-mcp
./claude-tools-mcp  # runs on localhost:8080

Docker:

docker build -t claude-tools-mcp .
docker run -p 8080:8080 claude-tools-mcp

Custom address:

./claude-tools-mcp --addr localhost:9000

Directory Tree

claude-tools-mcp/
├── cmd/
│   └── claude-tools-mcp/   # CLI entry point (Cobra)
├── internal/
│   └── tools/              # Tool implementations
│       ├── bash.go         # bash tool with timeout + background support
│       ├── bash_output.go  # retrieve background process output
│       ├── kill_shell.go   # terminate background processes
│       ├── read.go         # file read with offset/limit
│       ├── write.go        # file write
│       ├── edit.go         # exact string replacement
│       ├── glob.go         # glob pattern file finder
│       ├── grep.go         # ripgrep-backed search
│       ├── list_shells.go  # list background shells
│       ├── server.go       # MCP server registration
│       └── common.go       # shared utilities (constraints, etc.)
├── Dockerfile
├── Dockerfile.runtime      # Pre-built base image (GHCR)
├── CLAUDE.md               # Architecture docs
└── lefthook.yml            # Git hooks config

Runtime Dependencies

  • Go 1.25.1+
  • rg (ripgrep) for grep tool
  • MCP Go SDK (github.com/modelcontextprotocol/go-sdk)
  • Cobra for CLI
  • mimetype for file type detection

Transport

HTTP (listening on configurable address). Not stdio — designed for remote access.

Constraints (from common.go)

  • Max file size: 10MB
  • Max output: ~100k tokens
  • Max grep/glob results: 1000 lines
  • ReadHeaderTimeout and IdleTimeout for slowloris protection

Published Runtime Image

ghcr.io/mathematic-inc/claude-tools-mcp-runtime:latest

03

Components

Claude Tools MCP Server — Components

MCP Tools (8)

Tool Description
bash Execute shell commands; supports timeout and background execution mode
bash_output Retrieve output from a previously-started background shell process
kill_shell Terminate a background shell process by ID
read Read a file with optional line offset and limit
write Write content to a file on disk
edit Exact string replacement in a file (finds old_string, replaces with new_string)
glob Find files matching a glob pattern
grep Search file contents using ripgrep (regex support, multiple output modes)

Additional tool inferred from source: | list_shells | List all active background shell processes |

State Maintained (stateful exceptions)

  • File modification tracking: Detects when files are edited externally
  • Background shell management: Tracks long-running bash processes by ID

No Skills, Commands, Hooks

This is an MCP server only. It ships no Claude Code skills, slash commands, or hooks.

No Templates

No file scaffolds or instruction templates.

CLAUDE.md

An architecture documentation file (not a skill instruction file). Describes the internal design and tool contracts.

CLI

Single binary with one flag: --addr <host:port> (defaults to localhost:8080).

Docker Image

Two Dockerfiles:

  • Dockerfile.runtime — base image with all tools pre-installed (Go, ripgrep, dev tools)
  • Dockerfile — builds Go binary, uses runtime base image
05

Prompts

Claude Tools MCP Server — Prompts

Note on Prompts

Claude Tools MCP Server is an infrastructure component — a Go binary implementing the MCP protocol. It ships no instruction documents, skill files, or prompt templates. The tool definitions (names, descriptions, input schemas) constitute the only "prompts" in the system.

Tool Descriptions (from source code)

These are the tool descriptions that get sent to any MCP client in the tools/list response:

bash tool (verbatim from server.go):

"Execute shell commands with timeout support and background execution"

edit tool:

"Perform exact string replacements in files"

read tool:

"Read files with line offset/limit support"

grep tool:

"Search file contents using ripgrep (regex support, multiple output modes)"

These descriptions are minimal — they convey the tool signature but not usage patterns. The expectation is that the MCP client (an AI agent) infers usage from the input schema rather than a rich description.

CLAUDE.md (Architecture Docs)

The CLAUDE.md in the repo describes the server's internal architecture for developers, not for AI consumption. It is not a skill instruction file.

Prompting Technique Classification

  • Schema-driven: Tools are self-described via JSON schemas in the tools/list response
  • No progressive disclosure: All 8 tool schemas are always available; no lazy loading
  • No instruction layer: No CLAUDE.md with agent instructions, no skills, no system prompt
09

Uniqueness

Claude Tools MCP Server — Uniqueness

differs_from_seeds

Closest seed is ccmemory (Archetype 3 — MCP-anchored toolserver). But ccmemory exposes memory/knowledge graph tools; claude-tools-mcp exposes file system and shell execution tools. The key difference: ccmemory's tools are domain-specific (memory management), while claude-tools-mcp's tools are infrastructure primitives (bash, file I/O). Also closer to claude-flow (MCP server with many tools) but claude-flow's tools are workflow orchestration primitives, not file system tools. None of the 11 seeds expose Claude Code's own built-in tool surface as an MCP server.

Positioning

This server solves the "remote tool access" problem: an agent running elsewhere (cloud, another machine, a different IDE) needs Claude Code's bash/file tools without needing Claude Code installed. It's infrastructure plumbing, not a workflow methodology.

Distinctive Opinion

By mirroring Claude Code's exact tool names and behaviors (bash, read, write, edit, glob, grep), the server enables drop-in compatibility with agents written to use Claude Code's tools — the same prompts that work in Claude Code may work with this server.

Observable Failure Modes

  1. No sandboxing: Path traversal is blocked, but commands run as the server process user — a compromised MCP client has full shell access
  2. HTTP-only: Not stdio; some MCP clients expect stdio transport, requiring a proxy
  3. Background shell state loss: Server restart loses all tracked background processes
  4. ripgrep dependency: grep tool requires rg on PATH; server fails gracefully if missing, but functionality is reduced
  5. No auth layer: No authentication on the HTTP endpoint — should not be exposed publicly

What Makes It Novel vs. the 11 Seeds

  • Only framework that exposes Claude Code's own native tools as a standalone MCP server
  • Only Go-based MCP server in this batch
  • Only server designed for horizontal scaling (stateless HTTP, Docker, GHCR base image)
  • Only framework explicitly built by a non-profit (mathematic-inc)
04

Workflow

Claude Tools MCP Server — Workflow

Server Lifecycle

1. go build -o claude-tools-mcp ./cmd/claude-tools-mcp
2. ./claude-tools-mcp --addr localhost:8080
3. Any MCP client connects to http://localhost:8080
4. Client calls tools via MCP protocol
5. Server executes on local filesystem
6. Server responds with tool output
7. SIGINT/SIGTERM → graceful shutdown (in-flight requests complete)

Example Tool Usage Sequence

MCP Client → tools/list           → server responds with 8 tool schemas
MCP Client → bash(cmd="ls -la")  → server executes, returns output
MCP Client → read(path="src/main.go", limit=50) → returns first 50 lines
MCP Client → edit(path="src/main.go", old="foo", new="bar") → returns diff
MCP Client → glob(pattern="**/*.go") → returns matching file paths
MCP Client → grep(pattern="TODO", paths=["src/"]) → returns ripgrep results

Background Execution Workflow

MCP Client → bash(cmd="long-running-command", background=true) → returns shell_id
MCP Client → bash_output(shell_id="abc123") → returns buffered output so far
MCP Client → kill_shell(shell_id="abc123") → terminates process

Approval Gates

None. The server executes all valid tool calls immediately.

Phase/Artifact Table

Phase Description Artifact
Start server Build and run binary Listening HTTP server
Tool call MCP client sends request stdout/stderr response
File modification edit/write tool Modified file on disk
Background shell bash with background=true shell_id for tracking

Error Handling

  • Relative paths rejected: 400 error
  • File > 10MB: truncated or rejected
  • Output > ~100k tokens: truncated
  • SIGTERM during request: request completes, then shutdown
06

Memory Context

Claude Tools MCP Server — Memory & Context

State

Mostly stateless. Two exceptions:

  1. File modification tracking: In-memory map of file paths → last-known modification time. Used to detect external edits (when a file changed between tool calls).

  2. Background shell management: In-memory map of shell IDs → process objects + output buffers. Persists within a server run but lost on restart.

No Cross-Session Memory

When the server restarts, all background shell state is lost. No persistent storage.

Context Window Impact

The server's MCP tools always load their full schemas into the MCP client's context. No progressive disclosure. With 8 tools, the context overhead is small (likely 2k-5k tokens depending on schema verbosity).

Token Limits

The server enforces output limits to protect the MCP client's context window:

  • File reads: configurable line offset/limit
  • Grep/glob: max 1000 results
  • Total output: ~100k token maximum

State Files

None. The server writes no state files. It operates on the caller's filesystem (via write/edit tools) but maintains no index of its own.

07

Orchestration

Claude Tools MCP Server — Orchestration

Role in Multi-Agent Systems

This server acts as a tool provider in a larger multi-agent architecture. It does not orchestrate agents — it provides the primitive tools that agents use. A typical use case: an orchestration system (e.g., a Python agent using the MCP client SDK) needs to perform file operations on a remote machine; it connects to claude-tools-mcp to access bash, read, write, and grep.

Execution Mode

event-driven — the server runs continuously, responding to MCP protocol requests.

Horizontal Scaling

The server is designed for horizontal scaling:

  • Stateless except for in-memory shell tracking
  • Docker-compatible
  • No shared database needed

Multi-Model

Not applicable. The server is model-agnostic — any MCP client (any LLM or non-LLM system) can call it.

Isolation

None built-in. The server executes commands on the host filesystem. Path validation prevents directory traversal but does not sandbox execution.

Potential Use as Remote Claude Code Tools

A key use case: running Claude Code remotely or in cloud environments where the full Claude Code CLI is not installed. The MCP client could be any agent needing file/shell access on a remote host.

Concurrency

The Go HTTP server handles concurrent requests. Background shells are tracked per-process, allowing multiple concurrent long-running commands.

08

Ui Cli Surface

Claude Tools MCP Server — UI & CLI Surface

Dedicated CLI Binary

Yes. Binary name: claude-tools-mcp

Attribute Value
Name claude-tools-mcp
Language Go
Is thin wrapper No — owns MCP server logic
Subcommands None — single binary with --addr flag
Default port 8080

Local UI / Dashboard

None. The server exposes only the MCP HTTP protocol endpoint.

Docker Support

Full Docker support:

  • Dockerfile for main image
  • Dockerfile.runtime for pre-built base (cached GHCR: ghcr.io/mathematic-inc/claude-tools-mcp-runtime:latest)
  • Docker Compose not documented

CI/CD

.github/ workflows present. .goreleaser.yml and release-please-config.json indicate automated releases via GitHub Actions.

Observability

Standard HTTP server logs. No structured logging or metrics endpoint documented.

Cross-Tool Portability

High — any MCP client can connect. Not tied to Claude Code. Works with Claude Code, Cursor (if MCP-over-HTTP supported), OpenCode, or any custom agent using the MCP client SDK.

Related frameworks

same archetype · same primary tool · same memory type

Taskmaster AI ★ 27k
A3 MCP-anchored

Converts a PRD into a dependency-ordered JSON task graph that AI coding agents execute one task at a time, eliminating context…

ccmemory ★ 1
A3 MCP-anchored

Accumulates decisions, corrections, and failed approaches from Claude Code sessions into a queryable Neo4j graph so each new…

Pimzino spec-workflow-mcp ★ 4.2k
A3 MCP-anchored

MCP server providing spec-driven development workflow with dashboard-backed approval gates, implementation logging, and VSCode…

MCP Shrimp Task Manager ★ 2.1k
A3 MCP-anchored

Convert natural language requests into structured AI development tasks with chain-of-thought enforcement, reflection gates, and…

Bernstein ★ 460
A3 MCP-anchored

Govern parallel CLI coding agents with a deterministic Python scheduler, HMAC-chained audit trail, and compliance-ready signed…

LeanSpec ★ 252
A3 MCP-anchored

Provides a unified spec CLI and MCP server over any existing spec backend (markdown, GitHub Issues, ADO), making spec-driven…