io.github.ayush-s-tomar/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 · Tools · Demo · Connect a client · Limitations · 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
|-- assets/                # demo GIF and screenshots
|-- .github/workflows/ci.yml
|-- pyproject.toml         # PyPI packaging config
|-- server.json            # MCP registry manifest
|-- requirements.txt
|-- requirements-dev.txt
|-- claude_desktop_config_snippet.json
|-- CONTRIBUTING.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.3, published 2026-10-25, 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

• [x] Publish to PyPI as an installable package
• [x] Publish to the official MCP server registry
• [x] Refresh the bundled project data (v1.0.2)
• [x] 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