https://github.com/mathematic-inc/claude-tools-mcp
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
https://github.com/mathematic-inc/claude-tools-mcp
claude claude-code docker file-tools go http-server mcp model-context-protocol shell-tools
Last synced: 2 months ago
JSON representation
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
- Host: GitHub
- URL: https://github.com/mathematic-inc/claude-tools-mcp
- Owner: mathematic-inc
- License: apache-2.0
- Created: 2025-10-26T18:10:48.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-03-11T01:03:56.000Z (3 months ago)
- Last Synced: 2026-03-11T06:09:24.543Z (3 months ago)
- Topics: claude, claude-code, docker, file-tools, go, http-server, mcp, model-context-protocol, shell-tools
- Language: Go
- Size: 113 KB
- Stars: 13
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 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
```bash
go build -o claude-tools-mcp ./cmd/claude-tools-mcp
```
### With Docker
```bash
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:**
```bash
# 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
```bash
# Default (localhost:8080)
./claude-tools-mcp
# Custom address
./claude-tools-mcp --addr localhost:9000
```
### With Docker
```bash
# 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](https://github.com/modelcontextprotocol/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](./CLAUDE.md) for detailed architecture documentation.
## Development
### Running Tests
```bash
# 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](https://github.com/modelcontextprotocol/go-sdk)
- [Cobra](https://github.com/spf13/cobra) for CLI
- [mimetype](https://github.com/gabriel-vasile/mimetype) for file type detection
- ripgrep (`rg`) must be installed for the grep tool
## Repository
[github.com/mathematic-inc/claude-tools-mcp](https://github.com/mathematic-inc/claude-tools-mcp)
## License
Apache-2.0 License. Copyright (c) Mathematic Inc. See [LICENSE](./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](https://github.com/sponsors/mathematic-inc).