Employee MCP Server

A small Model Context Protocol server that exposes an employee directory — backed by SQLite, validated with Pydantic — as a set of MCP tools and resources. Includes an interactive CLI client for exercising it without a full MCP-aware host.

Contents

• server.py — the MCP server: tools, resources, database access

• models.py — Pydantic schemas that validate every tool's input and shape its output

• seed_db.py — one-time script that creates and populates employees.db

• client.py — interactive REPL client for calling the server by hand

• tests/ — pytest suite for the server and models

Related MCP server: Employee Management MCP Server

Requirements

• Python 3.11+ (developed against 3.14)

• A virtual environment (the project expects one at .venv)

Setup

Create a virtual environment and install dependencies:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

For running the test suite, install the dev dependencies instead (this includes everything in requirements.txt plus pytest):

.venv/bin/pip install -r requirements-dev.txt

Create and seed the database (run once per checkout — it creates employees.db next to server.py):

.venv/bin/python seed_db.py

employees.db is gitignored, so every fresh checkout needs this step. To wipe and reseed an existing database:

.venv/bin/python seed_db.py --force

Data model

Two tables, one employee record per id:

• employees(id, name, role)

• skills(id, employee_id, skill) — many rows per employee, cascade-deleted with the employee

Input to every write tool is validated by a Pydantic model in models.py before it reaches the database: name/role can't be blank, skills must contain at least one non-empty entry, and employee_id must be a positive whole number. A tool called with bad input gets back a clear error message (e.g. employee_id must be a positive whole number, got 'abc') instead of a stack trace or a silent failure.

Running the server

The server speaks MCP over stdio and isn't meant to be run standalone in a terminal — it's launched as a subprocess by an MCP client. client.py does this for you via StdioServerParameters, spawning server.py with the venv's Python interpreter.

To use it from an MCP-aware host (e.g. Claude Desktop, Claude Code), point the host's MCP config at:

{
  "mcpServers": {
    "employees": {
      "command": "/absolute/path/to/mcp_tool/.venv/bin/python",
      "args": ["/absolute/path/to/mcp_tool/server.py"]
    }
  }
}

Tools

Every tool also declares an output schema (an Employee or DeleteResult shape), so a schema-aware client sees structured results, not just text.

Resources

Using the interactive client

client.py opens one MCP session and gives you a REPL to call tools and read resources by hand:

.venv/bin/python client.py

> list
> get 101
> search an
> byskill AWS
> add Zara Khan | Data Scientist | Python,SQL
> update 122 | role=Senior Data Scientist | skills=Python,SQL,Spark
> delete 122
> resource employees://all
> resource employees://101
> resources
> tools
> help
> quit

• add fields are pipe-separated: name | role | comma,separated,skills [| employee_id]

• update takes employee_id, then one or more field=value pairs (name=, role=, or skills=), pipe-separated

• Tool errors (e.g. validation failures) print inline and drop you back to the prompt — the session stays open

Running tests

.venv/bin/pip install -r requirements-dev.txt
.venv/bin/python -m pytest tests/

Tests point the server at a temporary SQLite database (via tmp_path + monkeypatch) and never touch the real employees.db.

Project layout

server.py              MCP server: tools, resources, DB access
models.py               Pydantic input/output schemas
seed_db.py              Creates and seeds employees.db
client.py               Interactive REPL client
employees.db            SQLite database (generated, gitignored)
requirements.txt        Runtime dependencies
requirements-dev.txt    Runtime + test dependencies
tests/test_server.py    Server/tool tests
tests/test_models.py    Pydantic model tests