claude-code-mcp-server

MCP server for Claude Code with 15 development tools
Clone → npm install → npm run build → point Claude Code at dist/index.js (or use the claude-code-mcp-server binary after npm link).

What is this?

claude-code-mcp-server is a Model Context Protocol (MCP) server that exposes filesystem, search, shell, Git, GitHub, Docker, HTTP, database, test runner, and notification tools to Claude Code and any other MCP-capable client. It speaks JSON-RPC over stdio (no open ports).

Features

Feature	Description
15 tools	Files, glob/grep, shell, Git, GitHub issues, Docker, HTTP, PostgreSQL/SQLite, tests, webhooks
MCP standard	Built with @modelcontextprotocol/sdk (McpServer + Zod input schemas)
Security	ALLOWED_PATHS, DENY_PATHS, ALLOWED_COMMANDS, READ_ONLY
Local-first	Runs on your machine; no cloud dependency

Requirements

• Node.js 20+ (22+ recommended; matches Dockerfile)

Installation

cd claude-code-mcp-server
npm install
npm run build

Copy .env.example to .env and adjust variables as needed.

Quick start

1. Build

npm run build

This emits JavaScript to dist/. The repo does not require committing dist/; CI or local builds generate it.

2. Configure Claude Code

Add to ~/.claude/settings.json or project-local config:

{
  "mcpServers": {
    "dev-tools": {
      "command": "node",
      "args": ["/absolute/path/to/claude-code-mcp-server/dist/index.js"],
      "env": {
        "ALLOWED_PATHS": "/home/user/projects",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Restart Claude Code. Example prompts:

• Read README.md in this repo.
• Show git_status for the project.
• Run npm test via run_tests.

3. Run standalone (stdio)

npm start

The process reads/writes MCP messages on stdin/stdout.

4. CLI binary (optional)

After npm run build, you can run npx . from the repo root or npm link to install the claude-code-mcp-server command (see package.json "bin").

Tool reference

Tool	Purpose
read_file	Read a text file (optional utf8 / base64)
write_file	Write a file (blocked if READ_ONLY=true)
list_directory	List one directory level
glob	File search with fast-glob patterns
grep	Regex search over text files under a path
shell_exec	Run a shell command; first token must be in ALLOWED_COMMANDS
git_status	git status --porcelain=v1 -b
git_commit	git commit -m (does not auto-stage)
git_push	git push [remote] [branch]
github_create_issue	Create an issue via GitHub REST API (GITHUB_TOKEN)
docker_ps	docker ps with JSON lines (--format '{{json .}}')
http_request	fetch()-based HTTP client (GET/HEAD omit body)
db_query	SELECT / WITH only; Postgres URL or SQLite path via DB_CONNECTION_STRING
run_tests	Run a test command with captured output (same allowlist as shell)
send_notification	Slack Incoming Webhook (SLACK_WEBHOOK_URL) or generic JSON webhook (NOTIFICATION_WEBHOOK_URL)

Tool results are returned as text JSON in MCP content blocks.

Configuration

Environment variables (also loadable from .env via dotenv):

Variable	Purpose
ALLOWED_PATHS	Comma-separated roots for file tools and SQLite paths (default: server cwd)
DENY_PATHS	Comma-separated prefixes that always fail
ALLOWED_COMMANDS	First token allowlist for shell_exec / run_tests (defaults include npm, node, git, docker, …)
READ_ONLY	If true, blocks write_file, git_commit, git_push
GITHUB_TOKEN	For github_create_issue
DB_CONNECTION_STRING	PostgreSQL: postgresql://… SQLite: plain path (./data.db), absolute path, or file: / file:// URL (file must sit under ALLOWED_PATHS)
SLACK_WEBHOOK_URL / NOTIFICATION_WEBHOOK_URL	For send_notification
DEFAULT_SHELL	Unix shell for shell_exec / run_tests (default /bin/sh + -c)

Architecture

Claude Code  →  JSON-RPC (stdio)  →  claude-code-mcp-server
                                         ├── security (paths, commands)
                                         └── tools (file, search, shell, …)

Adding custom tools

Import McpServer from @modelcontextprotocol/sdk/server/mcp.js, reuse loadSecurityConfig / resolveSafePath from src/mcp/security.ts, and call server.registerTool in a new module; register it from src/mcp/router.ts, then npm run build.

Example pattern:

import { z } from 'zod';

server.registerTool(
  'hello',
  {
    description: 'Example tool',
    inputSchema: { name: z.string() },
  },
  async ({ name }) => ({
    content: [{ type: 'text', text: JSON.stringify({ hello: name }) }],
  }),
);

Docker

docker build -t claude-mcp-server .
docker run -i --rm \
  -v /home/user/projects:/workspace \
  -e ALLOWED_PATHS=/workspace \
  claude-mcp-server

Use -i so stdio stays open for MCP.

Development

npm run build          # TypeScript → dist/
npm test               # Vitest (unit + MCP integration)
npm run test:tools     # tests/tools/**
npm run test:integration # tests/integration/**

npm publish runs prepublishOnly first so dist/ is always built before the package ships.

Note: If your project path contains special characters (e.g. :), npm may not put local node_modules/.bin on PATH. This repo’s scripts call the TypeScript and Vitest binaries by explicit path so npm run build and npm test still work.

Project layout

claude-code-mcp-server/
├── src/
│   ├── mcp/
│   │   ├── router.ts      # registers all tools
│   │   └── security.ts    # path / command policy
│   ├── tools/             # one module per domain (+ run-shell.ts shared helper)
│   └── index.ts           # stdio entry
├── tests/
├── package.json
├── package-lock.json
├── tsconfig.json
├── vitest.config.ts
├── .env.example
├── .gitignore
├── .dockerignore
├── Dockerfile
├── LICENSE
└── README.md

Resources

• Model Context Protocol
• Claude Code
• MCP TypeScript SDK

License

MIT — see LICENSE.