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"],
      "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.