# personal-mcp-server

A small [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes personal project data as tools any MCP client can call.

## What is MCP?

MCP is an open protocol that lets AI assistants (like Claude Desktop or Claude Code) call out to external "servers" for tools, resources, and data — instead of the model having to guess or hallucinate. A client (the assistant) connects to a server (this project) over stdio or SSE, and the server advertises tools the assistant can invoke, with typed inputs and text outputs. This project is a server: it wraps a few personal data sources — Spotify listening history, movie ratings, and GitHub repos — in a small toolset that a client can query in natural language ("what were my top artists in 2024?").

## Tools exposed

| Tool | Description | Data source |
|---|---|---|
| `spotify_top_artists(year?, limit?)` | Top artists by listening time | `sample_data/spotify_history.json` (**sample data**) |
| `spotify_top_tracks(year?, limit?)` | Top tracks by listening time | `sample_data/spotify_history.json` (**sample data**) |
| `search_movie_ratings(query?, genre?, min_rating?)` | Search personal movie ratings/notes | `sample_data/movie_ratings.json` (**sample data**) |
| `list_github_repos(username?, limit?)` | List a GitHub user's repos with descriptions | Live GitHub API |

The Spotify and movie data files are **clearly-labeled synthetic sample data** checked into the repo (`_note` field in each file) so the server runs out of the box without needing your real Spotify export or a personal ratings database. Swap in your own files with the same shape to use real data — no code changes required as long as the JSON schema matches.

The GitHub tool calls the live GitHub REST API. It works unauthenticated for public data (subject to GitHub's stricter unauthenticated rate limits) or authenticated via a `GITHUB_TOKEN` environment variable.

## Running the server

Requires Python 3.10+.

```bash
# Install dependencies
pip install -r requirements.txt
# (or: pip install -e .)

# Optional: for live/authenticated GitHub calls
export GITHUB_TOKEN=ghp_your_token_here

# Run the server directly (stdio transport)
python server.py

# Or use the MCP CLI dev tool (auto-reload + inspector UI)
mcp dev server.py
```

## Connecting from Claude Desktop

Add this server to your Claude Desktop config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "personal-data": {
      "command": "python",
      "args": ["/absolute/path/to/personal-mcp-server/server.py"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

Restart Claude Desktop, then ask something like "What were my top Spotify artists in 2024?" or "List my GitHub repos."

## Connecting from Claude Code

Claude Code can attach to local MCP servers the same way — via its MCP server configuration (see Claude Code docs for `claude mcp add`), pointing at the same `command`/`args` shown above.

## Project structure

```
personal-mcp-server/
├── server.py                        # MCP server + tool definitions
├── sample_data/
│   ├── spotify_history.json         # SAMPLE synthetic Spotify streaming history
│   └── movie_ratings.json           # SAMPLE synthetic movie ratings/notes
├── pyproject.toml
├── requirements.txt
└── README.md
```