Claude Tools MCP Server

An MCP (Model Context Protocol) server that exposes Claude Code's file and shell manipulation tools over HTTP, allowing any MCP client to use these tools remotely.

Features

This server provides the following tools:

• bash: Execute shell commands with timeout support and background execution
• bash_output: Retrieve output from background shell processes
• kill_shell: Terminate background shell processes
• read: Read files with line offset/limit support
• write: Write files to disk
• edit: Perform exact string replacements in files
• glob: Find files using glob patterns
• grep: Search file contents using ripgrep (regex support, multiple output modes)

Installation

From Source

go build -o claude-tools-mcp ./cmd/claude-tools-mcp

With Docker

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

Docker Build Optimization

The Docker image uses a pre-built runtime base image (Dockerfile.runtime) that contains all development tools and dependencies. This runtime image is automatically built and published to GitHub Container Registry (GHCR) whenever Dockerfile.runtime or the workflow file changes.

Benefits:

• Significantly faster builds (only compiles Go binary, not installing all tools)
• Consistent runtime environment across deployments

Building the runtime image locally:

# Build the runtime base image
docker build -f Dockerfile.runtime -t claude-tools-runtime .

# Build the main image using local runtime
docker build -t claude-tools-mcp .

The published runtime image is available at: ghcr.io/mathematic-inc/claude-tools-mcp-runtime:latest

Usage

Starting the Server

# Default (localhost:8080)
./claude-tools-mcp

# Custom address
./claude-tools-mcp --addr localhost:9000

With Docker

# Default port (8080)
docker run -p 8080:8080 claude-tools-mcp

# Custom port
docker run -e PORT=9000 -p 9000:9000 claude-tools-mcp

Configuration

The server runs in stateless mode, allowing each HTTP request to be handled independently. This enables horizontal scaling and simpler deployment.

Security Features

• Timeout protection: Prevents slowloris attacks with ReadHeaderTimeout and IdleTimeout
• Graceful shutdown: Responds to SIGINT/SIGTERM, allowing in-flight requests to complete
• Path validation: Rejects relative paths to prevent directory traversal
• File size limits: 10MB max file size, ~100k token max output
• Result limits: Maximum 1000 lines for grep/glob results

Architecture

The server uses the MCP Go SDK to expose tools over HTTP. All tools are stateless except for:

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

See CLAUDE.md for detailed architecture documentation.

Development

Running Tests

# All tests
go test ./...

# Specific package
go test ./internal/tools

# Specific test
go test -run TestFunctionName ./internal/tools

Dependencies

• Go 1.25.1+
• MCP Go SDK
• Cobra for CLI
• mimetype for file type detection
• ripgrep (rg) must be installed for the grep tool

Repository

github.com/mathematic-inc/claude-tools-mcp

License

Apache-2.0 License. Copyright (c) Mathematic Inc. See LICENSE for details.

This project is free and open-source work by a 501(c)(3) non-profit. If you find it useful, please consider donating.