mcp-server-toolkit

<p align="center"> <img src="https://capsule-render.vercel.app/api?type=waving&height=220&text=MCP+Server+Toolkit&fontAlign=50&fontAlignY=40&color=timeGradient&customColorList=6,8,12,14,20&fontColor=ffffff&fontSize=36&animation=fadeIn" width="100%" /> </p>

<p align="center"> <img src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=600&size=22&pause=1000&color=9333EA&center=true&vCenter=true&multiline=true&repeat=true&width=700&height=120&lines=Production+MCP+Server+for+Claude+Desktop;8+Powerful+Tools+%7C+File+%2B+Shell+%2B+Web+%2B+AI;Drop-In+Config+for+Any+MCP+Client" alt="Typing SVG" /> </p>

<p align="center"> <img src="https://img.shields.io/badge/Python-3.11+-9333ea?style=for-the-badge&logo=python&logoColor=white" /> <img src="https://img.shields.io/badge/MCP-Model+Context+Protocol-9333ea?style=for-the-badge&logo=anthropic&logoColor=white" /> <img src="https://img.shields.io/badge/Anthropic-Claude+Sonnet-9333ea?style=for-the-badge&logo=anthropic&logoColor=white" /> <img src="https://img.shields.io/badge/aiohttp-Async+Web-9333ea?style=for-the-badge&logo=aiohttp&logoColor=white" /> <img src="https://img.shields.io/badge/DuckDuckGo-Search-9333ea?style=for-the-badge&logo=duckduckgo&logoColor=white" /> <img src="https://img.shields.io/badge/License-MIT-9333ea?style=for-the-badge" /> </p>

---

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

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

---

<p align="center"> <img src="https://capsule-render.vercel.app/api?type=waving&height=120&section=footer&color=timeGradient&customColorList=6,8,12,14,20&animation=fadeIn" width="100%" /> </p>