MCP 服务器

mcp-server-toolkit

A production-ready MCP server providing 8 tools for file operations, shell command execution, web search and fetching, plus AI-powered code review and text summarization, with built-in security controls.

README

Overview

MCP Server Toolkit is a production-ready Model Context Protocol server that exposes 8 powerful tools to Claude Desktop and any MCP-compatible client. With a single config entry, Claude gains the ability to read and write files, run shell commands, search the web, fetch URLs, and perform AI-powered code reviews and text summarisation — all with built-in security controls.

Features

Tool	Description
`read_file`	Read file contents with size guard (10 MB limit) and encoding detection
`write_file`	Write / create files, restricted to CWD with auto parent-dir creation
`list_directory`	List directory with file types, sizes, and modified timestamps
`execute_shell`	Run shell commands against a strict allowlist with dangerous-pattern blocking
`web_search`	DuckDuckGo Instant Answer API — returns structured results with snippets and URLs
`fetch_url`	Fetch and parse any web page, strips nav/ads/scripts, returns clean text + links
`code_review`	Claude-powered code review with issues, severity ratings, security analysis, verdict
`summarise_text`	Claude-powered summarisation with key points, structured paragraphs, takeaway

Security Model

Path sanitisation: Blocks .. traversal, symlink abuse, and access to sensitive system files (~/.ssh, ~/.aws/credentials, /etc/shadow, etc.)
Write isolation: write_file is restricted to the current working directory
Command allowlist: execute_shell only permits a curated set of safe commands (ls, grep, git, python, curl, etc.)
Pattern blocking: Chains like ; rm, | sh, fork bombs, and decode-and-exec patterns are rejected before execution
Output truncation: Shell stdout/stderr capped at 512 KB; web content at 256 KB

Architecture

mcp-server-toolkit/
│
├── server/
│   ├── main.py                  # MCP server — tool registration & dispatch
│   ├── security.py              # Path sanitisation + command allowlist
│   └── tools/
│       ├── __init__.py          # Re-exports all tool functions
│       ├── file_tools.py        # read_file, write_file, list_directory
│       ├── shell_tools.py       # execute_shell (with validation)
│       ├── web_tools.py         # web_search (DuckDuckGo), fetch_url (aiohttp + BS4)
│       └── ai_tools.py          # code_review, summarise_text (Claude API)
│
├── claude_desktop_config.json   # Drop-in config for Claude Desktop
├── requirements.txt
└── README.md

Request flow:

Claude Desktop  →  stdio transport  →  server/main.py (MCP Server)
                                              ↓ dispatch
                                   tools/file_tools.py   ← local filesystem
                                   tools/shell_tools.py  ← subprocess (allowlisted)
                                   tools/web_tools.py    ← aiohttp / DuckDuckGo
                                   tools/ai_tools.py     ← Anthropic Claude API

Quick Start

1. Clone & Install

git clone https://github.com/isamkhan1809/mcp-server-toolkit
cd mcp-server-toolkit
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

2. Set Environment Variables

export ANTHROPIC_API_KEY="sk-ant-..."   # required for code_review + summarise_text

3. Test the Server

python -m server.main

The server communicates over stdio and is ready for MCP client connections.

4. Connect to Claude Desktop

Copy the following into your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server-toolkit": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "/absolute/path/to/mcp-server-toolkit",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-your-key-here",
        "PYTHONPATH": "/absolute/path/to/mcp-server-toolkit"
      }
    }
  }
}

Restart Claude Desktop. You will see the toolkit listed under available tools.

Project Structure

server/main.py          — MCP server, tool registration, call dispatcher
server/security.py      — sanitise_path(), validate_command(), blocked prefixes & patterns
server/tools/
  file_tools.py         — read_file, write_file, list_directory
  shell_tools.py        — execute_shell (subprocess + security gate)
  web_tools.py          — web_search (DuckDuckGo API), fetch_url (aiohttp + BeautifulSoup)
  ai_tools.py           — code_review, summarise_text (Claude claude-sonnet-4-5)
claude_desktop_config.json  — Ready-to-paste Claude Desktop config
requirements.txt

Usage Examples

Once connected to Claude Desktop, you can ask Claude:

"Read the file ./src/main.py and review it for bugs"
→ calls read_file, then code_review

"Search for 'MCP protocol specification' and summarise the top result"
→ calls web_search, then fetch_url, then summarise_text

"List my project directory and show me what's in the src folder"
→ calls list_directory

"Run git status in my project"
→ calls execute_shell("git status")

"Write a new file called notes.md with today's meeting notes"
→ calls write_file

Configuration

Environment Variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	For AI tools	API key for `code_review` and `summarise_text`

Allowed Shell Commands

The following base commands are permitted by execute_shell:

ls  find  cat  head  tail  wc  file  stat  du  df
grep  awk  sed  sort  uniq  cut  tr  jq  diff
git  python  python3  pip  pip3  node  npm
pytest  ruff  mypy  black
echo  pwd  whoami  date  uname  env
curl  wget

To add a command, append it to ALLOWED_COMMANDS in server/security.py.

Extending with New Tools

Add your function to the appropriate server/tools/*.py file
Export it from server/tools/__init__.py
Register a new types.Tool entry in server/main.py's list_tools()
Add a dispatch branch in call_tool()