mcp-lab

MCP Lab is a development environment for building and testing custom MCP (Multi-Component Protocol) servers that integrate with AI tooling and VS Code-compatible workflows. It provides a modular framework for creating agent pipelines, prompt design, sampling control, and tool orchestration, along with example agents and tools to accelerate iteration. The lab emphasizes a lightweight, developer-centric approach suited for solo developers who want to prototype structured AI workflows and debug agent infrastructure. You can start by launching the basic MCP server, running tests, and then integrating with Claude Desktop or other environments by adding your server configuration to your MCP config file.

To use the server tools, begin with starting the MCP server using Python, then explore the supplied example agents and tools under src/agents and src/tools. You can test functionality with the included test suite and extend the framework by tweaking prompts, adjusting sampling controls, and adding or swapping tools (e.g., File Operations, Data Processing, API Integration, Code Analysis) to fit your workflow. For Claude Desktop integration, add a configuration entry pointing to your main server script, and ensure necessary API keys and settings are provided in your environment file.

Example usage scenario: start the server, run the test suite to validate behavior, then spawn a new agent configuration to orchestrate a simple data-processing task, using the provided tools to read, transform, and output results. This environment is designed for rapid prototyping and debugging of complex agent pipelines in a VS Code-friendly context.

Prerequisites

• Python 3.8+ (recommended latest stable)
• Git
• pip (comes with Python)
• Optional: virtual environment tool (venv, conda, etc.)

Installation steps

1. Clone the repository:

git clone https://github.com/harehimself/mcp-lab.git
cd mcp-lab

2. Create and activate a virtual environment (recommended):

python -m venv venv
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure your environment (copy example and edit):

cp .env.example .env
# Edit .env with your API keys and settings

5. Run the example server to verify:

python src/servers/main_server.py

6. (Optional) Run tests:

python tests/test_server.py

Environment variables: define API keys and any service credentials in .env as referenced by the server and tools. Common variables include API_KEY, API_SECRET, OPENAI_API_KEY, and any service-specific tokens for File Operations, API Integration, or Database Tools. If you extend with Claude Desktop integration, ensure any required OAuth tokens or desktop app credentials are included. Path considerations: the MCP server path used in the config should point to the actual main server entry script (e.g., src/servers/main_server.py). If your environment uses a virtual environment, activate it before running the server. For debugging, inspect src/servers and src/tools for logging hooks and error handling, and use the tests to validate changes before deployment. This project is designed to be lightweight and rapidly iterated; keep your custom agents modular and document tool interfaces for easier reuse.