Portfolio MCP Server

🗂️ Portfolio MCP Server

Ask an AI about my work. It answers from real data, not a PDF.

An MCP server that makes my AI project portfolio queryable.

Connect it to Claude, Cursor, or any MCP client and just ask.

[Quickstart](#-quickstart) · [Tools](#-tools) · [Demo](#-demo) · [Connect a client](#-connect-a-client) · [Limitations](#known-limitations) · [Roadmap](#roadmap)

⚡ Quickstart

The server command (clients launch it for you; run by hand, it just waits silently for a client):

uvx --with "mcp<2" portfolio-mcp-server

Add it to Claude Code with one line:

claude mcp add --scope user portfolio -- uvx --with "mcp<2" portfolio-mcp-server

Then ask:

*"What has Ayush built with LangGraph?"*

Prefer pip? pip install portfolio-mcp-server

💡 Why this exists

Most AI-developer portfolios are a list of links. This is a working MCP server built around my own portfolio, using the same protocol agentic products use to connect to tools. It is a real implementation of the spec and a direct answer to *"show me you've actually built with MCP."*

🧰 Tools

🧠 How it works

MCP client (Claude, Cursor, agents)  <--stdio-->  portfolio-mcp-server (FastMCP)  -->  bundled project data

The client launches the server as a local process and talks to it over stdio. The server answers each tool call from its bundled project data. Nothing is hosted, and no API keys are needed.

🎬 Demo

🎥 Full video walkthrough

https://github.com/user-attachments/assets/4c1b844a-087f-48a6-b156-bdef27282acc

*Setup → tool calls → live answers, end to end.*

🔌 Connect a client

Claude Code

claude mcp add --scope user portfolio -- uvx --with "mcp<2" portfolio-mcp-server

Claude Desktop

Open your config file:

If the file already has an mcpServers key, add "portfolio" inside it instead of overwriting the file.

Installed with pip:

{

"mcpServers": { "portfolio": { "command": "portfolio-mcp-server" } } }

Running from a cloned checkout (use the absolute path to server.py):

{

"mcpServers": { "portfolio": { "command": "python", "args": ["/absolute/path/to/portfolio-mcp-server/server.py"] } } }

Restart Claude Desktop and ask: *"What projects has Ayush built with FastAPI?"*

Cursor and other clients

Any MCP client that can launch a stdio server works. Use portfolio-mcp-server (after pip install) or the uvx command above as the server command.

🛠️ Development

Run from source

git clone https://github.com/ayush-s-tomar/portfolio-mcp-server.git

cd portfolio-mcp-server

python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate

pip install -r requirements.txt

Test it interactively with the MCP Inspector:

mcp dev server.py

This opens a browser UI where you can call each tool and inspect raw request and response payloads.

Testing & CI

Every push and pull request runs through GitHub Actions:

Run the same checks locally before opening a PR:

pip install -r requirements-dev.txt

ruff check . mypy server.py pytest

See .github/workflows/ci.yml.

Project structure

portfolio-mcp-server/

|-- portfolio_mcp_server/ | |-- init.py | -- server.py # packaged module (what PyPI ships) |-- server.py # top-level entry point (dev / MCP Inspector / CI) |-- tests/ | |-- smoke_test.py # stdio smoke test: calls all 5 tools, validates JSON schema | |-- test_tools.py # per-tool tests | |-- test_data.py # data integrity checks for the bundled projects | -- check_links.py # checks every URL in the data (runs weekly in CI) |-- assets/ # demo GIF and screenshots |-- .github/ | |-- workflows/ # ci.yml, links.yml | |-- ISSUE_TEMPLATE/ | |-- PULL_REQUEST_TEMPLATE.md | -- dependabot.yml |-- pyproject.toml # PyPI packaging config |-- server.json # MCP registry manifest |-- requirements.txt |-- requirements-dev.txt |-- claude_desktop_config_snippet.json |-- CHANGELOG.md |-- CONTRIBUTING.md |-- SECURITY.md -- LICENSE

Built with: Python 3.10+ · MCP Python SDK (FastMCP) · stdio transport · registered on the MCP registry as io.github.ayush-s-tomar/portfolio-mcp-server

⚠️ Known limitations

Warning: The installed package is a snapshot. pip install gets the portfolio as it was at that release (v1.0.4, published 2026-10-27, at the time of writing). Projects added and demo links changed since then won't appear until a new version is published, and tool responses can't yet say how current they are.

• Static project data. Tools read from bundled data, so updating a project means editing it and republishing. There is no live sync with the GitHub repos or portfolio site yet.
• stdio only. It works for local clients that can spawn the process, such as Claude Desktop, but there is no HTTP/SSE option yet for remote clients.
• One technology per search. search_projects_by_stack filters on a single technology per call, so "LangGraph *and* FastAPI together" isn't supported yet.

🗺️ Roadmap

Done

• Publish to PyPI as an installable package
• Publish to the official MCP server registry
• Refresh the bundled project data (v1.0.2)
• Weekly CI link check of every URL in the bundled data

Next

• Fetch project data from the portfolio site at startup, with the bundled snapshot as an offline fallback (one source of truth instead of two copies that drift apart)
• Return a last_updated date from every tool so an answer can say how current it is
• Support matching multiple technologies at once in search_projects_by_stack
• Add an HTTP/SSE transport option alongside stdio for remote clients

🌐 Also listed on

📄 License

Released under the MIT License.

---

Built by Ayush Singh Tomar

GitHub · LinkedIn · Portfolio

If this helped you build your own MCP server, a ⭐ on the repo is appreciated.

mcp-name: io.github.ayush-s-tomar/portfolio-mcp-server