whoami-mcp

A Model Context Protocol server that exposes a person's structured professional profile — experience, projects, skills, education, certifications — as MCP tools. Point Claude (or any MCP client) at it and it can answer questions about that person from real data instead of guesswork.

One package, three ways to use it:

• Library — npm i whoami-mcp, build your own integration on the tools.
• Local (stdio) — npx whoami-mcp for Claude Desktop.
• Deployable (HTTP) — a stateless Streamable-HTTP server you can host (Docker-ready).

Install

One click — pick your client:

Or follow a per-client guide:

Client	Guide
Cursor	installation/install-cursor.md
Claude Desktop	installation/install-claude-desktop.md
Claude Code	installation/install-claude-code.md
VS Code (Copilot)	installation/install-vscode.md
Windsurf	installation/install-windsurf.md
Remote / HTTP deploy	installation/install-http.md

After install, point the server at your profile.

Contents

• Install
• Tools
• Chat (optional)
• Your profile
• Local (stdio) — Claude Desktop
• Deploy (Streamable HTTP)
• Build on the library
• Layout
• License

Tools

Tool	Returns
get_profile	Name, role, company, location, bio, availability, preferred stack, links
get_experience	Work history: companies, roles, dates, descriptions, achievements
get_projects	Projects: tech stack, problem solved, your specific role, links
get_skills	Skills by category with proficiency levels
get_education	Education history + professional certifications

Chat (optional)

Set a chat provider and the server gains an extra ask tool — it answers free-form questions in the person's voice, grounded in the profile, instead of just returning raw data. Off by default (the data tools work without it).

It speaks the OpenAI-compatible /chat/completions API, so any provider works — set a base URL + model (+ key if needed):

Provider	CHAT_BASE_URL	CHAT_MODEL
OpenAI	https://api.openai.com/v1	gpt-4o-mini
Google	https://generativelanguage.googleapis.com/v1beta/openai	gemini-2.0-flash
Ollama (local, no key)	http://localhost:11434/v1	llama3.2
Groq	https://api.groq.com/openai/v1	llama-3.3-70b-versatile

CHAT_BASE_URL=https://api.openai.com/v1 CHAT_API_KEY=sk-... CHAT_MODEL=gpt-4o-mini \
  PROFILE_PATH=data/profile.json npm run start:http

Env: CHAT_BASE_URL, CHAT_MODEL (both required to enable), CHAT_API_KEY (optional), CHAT_TEMPERATURE (default 0.4). See .env.example.

Your profile

Every server reads one profile JSON with six top-level keys: basic, experience, projects, skills, education, certifications. See data/profile.example.json for the exact shape.

cp data/profile.example.json data/profile.json   # then edit

Point a server at it however suits your deploy (precedence top to bottom):

• PROFILE_URL — fetch the JSON over HTTP (a GitHub gist, your hosted profile API, any endpoint)
• PROFILE_PATH — read this file
• ./profile.json — default file in the working directory

Local (stdio) — Claude Desktop

{
  "mcpServers": {
    "whoami": {
      "command": "npx",
      "args": ["-y", "whoami-mcp", "whoami-stdio"],
      "env": { "PROFILE_PATH": "/abs/path/to/your/profile.json" }
    }
  }
}

From a clone instead: npm install && npm run build, then point command/args at node /abs/path/to/dist/stdio.js.

Other clients: Cursor · Claude Code · VS Code · Windsurf.

Deploy (Streamable HTTP)

A long-running, stateless HTTP server — host it anywhere that runs a container.

docker compose up --build      # serves MCP at http://localhost:8080/mcp

Without Docker:

npm install && npm run build
PROFILE_PATH=data/profile.json npm run start:http

Connect an MCP client to the endpoint:

{ "mcpServers": { "whoami": { "url": "http://localhost:8080/mcp" } } }

Health check: GET /health → {"status":"ok"}.

Full deploy + remote-client guide: installation/install-http.md.

Build on the library

npm i whoami-mcp

import { registerTools, type NormalizedProfile } from "whoami-mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({ name: "whoami", version: "1.0.0" });
registerTools(server, profile);   // profile: NormalizedProfile

whoami-mcp/http also exports createHttpHandler(profile, opts) for Next.js / fetch runtimes.

Layout

src/
  index.ts        library entry — TOOLS, registerTools, types
  http.ts         createHttpHandler (fetch/Next factory)  → exported as whoami-mcp/http
  tools.ts        the five tool definitions
  types.ts        NormalizedProfile + tool types
  register.ts     registerTools(server, profile)
  loadProfile.ts  read PROFILE_PATH / ./profile.json
  stdio.ts        bin: whoami-stdio
  http-server.ts  bin: whoami-http (deployable, SDK StreamableHTTP)

npm install
npm run build

License

MIT — see LICENSE.