Portfolio Mcp Server

⚡ 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

🔌 Connect a client

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

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

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

🛠️ Development

git clone https://github.com/ayush-s-tomar/portfolio-mcp-server.gitcd portfolio-mcp-server
python -m venv venvsource venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

mcp dev server.py

pip install -r requirements-dev.txtruff check .mypy server.pypytest

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.

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