Musicians MCP Server

Python MCP server for a classical musicians database stored in Supabase/PostgreSQL.

This project now supports both:

• trusted database read/review tools, and
• deterministic external-source enrichment/staging tools

for MusicBrainz and Wikidata.

The MCP client is the AI agent. This server does not call any LLM APIs internally.

Features

Core database tools

• health_check()
• search_musicians(query: str, limit: int = 10)
• get_musician_profile(musician_id: str)
• create_import_job(names: list[str], job_name: str | None = None)
• get_review_queue(limit: int = 20)
• approve_staged_musician(staged_profile_id: str)

External-source enrichment and staging tools

• resolve_musician_identity(name: str, limit: int = 5)
• fetch_wikidata_profile(qid: str)
• fetch_musicbrainz_artist(mbid: str)
• stage_musician_from_sources(...)
• detect_staged_profile_conflicts(staged_profile_id: str)
• process_import_job_next(import_job_id: str)
• process_import_job_batch(import_job_id: str, max_names: int = 5)

Project Structure

.
├── .env.example
├── pyproject.toml
├── README.md
└── src
    └── musicians_mcp
        ├── __init__.py
        ├── db.py
        ├── external_sources.py
        └── server.py

Requirements

• Python 3.11+
• Supabase project URL
• Supabase service role key
• a valid MusicBrainz User-Agent string
• a valid Wikimedia User-Agent string

Setup

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
cp .env.example .env

Update .env with:

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key
MUSICBRAINZ_USER_AGENT=ClassicalMusiciansMCP/0.1.0 (your-email-or-project-url)
WIKIMEDIA_USER_AGENT=ClassicalMusiciansMCP/0.1.0 (your-email-or-project-url)

User-Agent notes:

• MusicBrainz expects a descriptive User-Agent.
• Wikimedia also expects a descriptive User-Agent for automated access.
• A good format is: ClassicalMusiciansMCP/0.1.0 (your-email-or-project-url)

Run the Server

source .venv/bin/activate
python -m musicians_mcp.server

Or with the installed script:

source .venv/bin/activate
musicians-mcp

Example MCP Client Config

{
  "mcpServers": {
    "musicians": {
      "command": "/absolute/path/to/Musicians MCP/.venv/bin/python",
      "args": ["-m", "musicians_mcp.server"],
      "cwd": "/absolute/path/to/Musicians MCP",
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_SERVICE_ROLE_KEY": "your-supabase-service-role-key",
        "MUSICBRAINZ_USER_AGENT": "ClassicalMusiciansMCP/0.1.0 (your-email-or-project-url)",
        "WIKIMEDIA_USER_AGENT": "ClassicalMusiciansMCP/0.1.0 (your-email-or-project-url)"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

If your MCP client loads environment variables from the working directory, you can keep the values in .env instead.

Safety Rules

This server is intentionally conservative.

• It does not write directly to musicians.
• It does not auto-approve staged musicians.
• It does not call approve_staged_musician during staging or batch processing.
• It only stages facts that came from source-backed deterministic fetches.
• It writes review signals and ambiguity details into staged rows/audit logs.
• If identity resolution is ambiguous, it keeps the profile in review-oriented status instead of pretending the identity is verified.

Trusted promotion must still happen manually through:

• approve_staged_musician(p_staged_profile_id uuid)

External Source Behavior

MusicBrainz

The server can:

• search artists by name
• fetch artist details by MBID
• normalize aliases, artist type, country/area, life-span, disambiguation, and source URL

Wikidata

The server can:

• search entities by name
• fetch item details by QID
• normalize labels, description, aliases, dates, citizenship, occupations, instruments, notable works, websites, and selected external identifiers

Request discipline

Both source clients:

• always send configured User-Agent headers
• apply conservative pacing
• use retry logic for transient HTTP failures
• log every external request

Tool Summary

health_check()

Verifies that the server can connect to Supabase.

search_musicians(query, limit=10)

Searches musicians by:

• full_name
• display_name
• sort_name
• nationality
• primary_role

Returns:

• id
• full_name
• display_name
• nationality
• primary_role
• birth_date
• death_date
• confidence
• is_verified

get_musician_profile(musician_id)

Returns a single trusted musician plus related:

• fact_claims
• external_identifiers

create_import_job(names, job_name=None)

Creates an import job and returns:

• job_id
• total_names
• status

get_review_queue(limit=20)

Reads staged profiles from staged_musician_review_queue.

approve_staged_musician(staged_profile_id)

Manually approves a staged profile through the Postgres RPC.

resolve_musician_identity(name, limit=5)

Searches both Wikidata and MusicBrainz and returns ranked normalized candidates.

Each candidate includes:

• source
• external_id
• name
• description / disambiguation
• birth_date
• death_date
• country
• roles
• match_score
• source_url

This tool does not write to the database.

fetch_wikidata_profile(qid)

Fetches and normalizes one Wikidata item.

Returns:

• structured profile data
• raw key fields useful for debugging

This tool does not write to the database.

fetch_musicbrainz_artist(mbid)

Fetches and normalizes one MusicBrainz artist.

Returns:

• structured profile data
• raw key fields useful for debugging

This tool does not write to the database.

stage_musician_from_sources(...)

Resolves and stages a musician from deterministic external sources.

Behavior:

• if explicit external IDs are provided, it fetches those exact profiles
• otherwise it resolves likely candidates first
• only strong matches may be selected automatically
• ambiguous cases remain review-oriented
• inserts one row into staged_musician_profiles
• inserts source-backed rows into staged_fact_claims
• writes audit entries into import_audit_logs
• does not write to musicians
• does not call approval automatically

Returns:

• staged_profile_id
• status
• confidence
• selected_sources
• warnings

detect_staged_profile_conflicts(staged_profile_id)

Checks staged facts for conflicts such as:

• different birth dates
• different death dates
• different nationality/citizenship values
• inconsistent roles/occupations

Returns property-level conflict details.

process_import_job_next(import_job_id)

Processes exactly one pending name from an import job.

It:

• stages a single profile
• updates processed names safely
• writes audit logs
• never approves automatically

process_import_job_batch(import_job_id, max_names=5)

Processes up to max_names pending names.

Returns per-name:

• staging results
• errors
• job status progression

Recommended Manual Test Flow

1. Run health_check
2. Run resolve_musician_identity("Claude Debussy")
3. Run fetch_wikidata_profile on the selected QID
4. Run fetch_musicbrainz_artist on the selected MusicBrainz artist ID
5. Run create_import_job(["Claude Debussy", "Maurice Ravel"])
6. Run process_import_job_next(job_id)
7. Run get_review_queue()
8. Run detect_staged_profile_conflicts(staged_profile_id)
9. Only then run approve_staged_musician manually if the staged record is acceptable

Local Verification Commands

After setup, these are the main commands to run locally:

source .venv/bin/activate
python -m pip install -e .
python -m compileall src
python -c "import sys; sys.path.insert(0, 'src'); import musicians_mcp.server; print('server import ok')"
python -m musicians_mcp.server

Notes on Schema Flexibility

This implementation is intentionally defensive around the import/staging tables because exact column layouts were not fully specified here.

In particular, db.py uses fallback payload shapes for:

• musician_import_jobs
• staged_musician_profiles
• staged_fact_claims
• import_audit_logs

That makes the first version more resilient, but if you share the exact table schemas next, I can tighten the insert/update logic to match them precisely and reduce fallback branching.