MCP Server Toolkit

A production-ready MCP server exposing filesystem, web search, SQLite, and system tools — plug directly into Claude Desktop or any MCP-compatible client.

---

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants like Claude securely call external tools — giving them real-time access to your filesystem, databases, and the web without you having to paste content into the chat manually.

---

Features

• Filesystem — read_file returns any text file with numbered lines; search_files globs a directory tree. Both tools enforce a configurable ROOT_DIR so path-traversal attacks are impossible.
• Web Search — web_search queries DuckDuckGo's free JSON API. No API key, no rate limits, async with a 10 s timeout.
• SQLite — query_sqlite runs SELECT-only queries and returns typed columns + rows; list_tables shows the schema at a glance.
• System — get_system_info snapshots OS, Python version, CPU count, memory usage, free disk, hostname, and uptime in one call.

---

Quick Start

Option 1 — pip

pip install git+https://github.com/plasmacat420/mcp-server-toolkit.git
mcp-toolkit          # starts the server on stdio (Claude Desktop mode)

Option 2 — Docker

docker pull ghcr.io/plasmacat420/mcp-server-toolkit:latest
docker run -it ghcr.io/plasmacat420/mcp-server-toolkit:latest

Option 3 — Docker Compose (recommended for SSE / networked use)

git clone https://github.com/plasmacat420/mcp-server-toolkit
cd mcp-server-toolkit
cp .env.example .env          # edit ROOT_DIR if needed
docker compose up

The SSE endpoint is then available at http://localhost:8000.

---

Claude Desktop Integration

Add the following block to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "mcp-toolkit": {
      "command": "mcp-toolkit",
      "env": {
        "ROOT_DIR": "/Users/you/projects"
      }
    }
  }
}

Restart Claude Desktop — the four tool categories appear automatically in every conversation.

---

Tool Reference

Tool	Description	Parameters	Returns
read_file	Read a text file with line numbers	path: str	{content, path, lines, size_bytes}
search_files	Glob-search inside a directory	directory: str, pattern: str, recursive: bool = True	{results[], count}
web_search	DuckDuckGo search (no key needed)	query: str, max_results: int = 5	{results[], query, count}
query_sqlite	Execute a SELECT query	db_path: str, sql: str	{columns[], rows[], row_count}
list_tables	List all tables in a SQLite DB	db_path: str	{tables[], count}
get_system_info	Host OS / resource snapshot	(none)	{os, cpu_count, memory_gb, …}

---

CLI Usage

The mcp-client binary lets you call any tool from your terminal:

# Search for Python files
mcp-client search-files . "*.py"
# {"results": [...], "count": 12}

# Read a file
mcp-client read-file src/mcp_toolkit/server.py
# {"content": "   1 | \"\"\"MCP Server Toolkit...", "lines": 34, ...}

# Web search
mcp-client web-search "python asyncio tutorial" --max-results 3
# {"results": [{"title": "...", "url": "...", "snippet": "..."}], ...}

# Query a SQLite database
mcp-client query-db examples/sample.db "SELECT name, email FROM users LIMIT 3"
# {"columns": ["name", "email"], "rows": [["Alice Johnson", "alice@..."]], ...}

# System snapshot
mcp-client system-info
# {"os": "Linux", "cpu_count": 8, "memory_gb": 15.87, ...}

# Full demo against sample.db
mcp-client demo

---

Development

git clone https://github.com/plasmacat420/mcp-server-toolkit
cd mcp-server-toolkit

# Install with dev extras
pip install -e ".[dev]"

# Create the sample database
python examples/create_db.py

# Run the test suite
pytest -v

# Lint + format check
ruff check .
ruff format --check .

# Auto-fix
ruff check . --fix && ruff format .

# Full demo (requires sample.db)
python examples/demo.py

Running a single test

pytest tests/test_filesystem.py::test_read_file_success -v

---

Architecture

The server is built on FastMCP, which handles the MCP wire protocol. Each tool category lives in its own module under src/mcp_toolkit/tools/; the modules export plain async functions that know nothing about MCP. server.py creates the FastMCP instance, imports every tool function, and registers them with mcp.tool(). Configuration is a single pydantic-settings BaseSettings object (config.py) that reads from environment variables or a .env file. The CLI client (client/cli.py) imports the same async functions directly — no MCP protocol involved — making it easy to smoke-test individual tools.

src/mcp_toolkit/
├── server.py        ← FastMCP app + tool registration
├── config.py        ← pydantic-settings Settings singleton
└── tools/
    ├── filesystem.py   read_file, search_files
    ├── websearch.py    web_search
    ├── database.py     query_sqlite, list_tables
    └── system.py       get_system_info

---

License

MIT © plasmacat420