withPICA — Music Catalog Management

Created By
withpica2 months ago
Manage your music catalog through conversation. tools across catalog, enrichment, business, discovery, media, and comms. Works, recordings, credits, splits, agreements, royalties, licensing — all through AI. No API key needed. Connect and say "sign me in to pica" — you get a magic link in chat. Free account, no credit card. Enrichment from Spotify, MusicBrainz, MLC, ISNI, Discogs, YouTube. Export to CWR, song registrations, catalog asset reports. Built for songwriters, producers, artists, managers, publishers and independent labels.
Overview

@withpica/mcp-server
TypeScript icon, indicating that this package has built-in type declarations

2.48.0 • Public • Published

PICA MCP Server

Model Context Protocol (MCP) server for the PICA Platform. Enables any MCP-compatible AI assistant to interact with your PICA music catalog.

What is MCP?

The Model Context Protocol (MCP) is an open standard that enables AI assistants to securely access external data and functionality. With this MCP server, any MCP-compatible AI can interact with your PICA catalog.

Compatible AI Assistants

  • Claude Desktop - Anthropic's desktop AI assistant
  • ChatGPT - OpenAI's assistant (when MCP support is available)
  • Custom AI tools - Any application that implements the MCP protocol
  • Future AI assistants - As more tools adopt MCP

Features

24 AI-Callable Tools

Works Management (8 tools)

  • pica_works_list - List musical works
  • pica_works_get - Get work details
  • pica_works_create - Create new work
  • pica_works_update - Update work
  • pica_works_delete - Delete work
  • pica_works_verify - Verify work
  • pica_works_search - Search works
  • pica_works_bulk_delete - Delete multiple works

People Management (8 tools)

  • pica_people_list - List people
  • pica_people_get - Get person details
  • pica_people_create - Create new person
  • pica_people_update - Update person
  • pica_people_delete - Delete person
  • pica_people_search - Search people
  • pica_people_enrich_isni - Enrich from ISNI
  • pica_people_enrich_musicbrainz - Enrich from MusicBrainz

Recordings Management (5 tools)

  • pica_recordings_query - List/search recordings; filter by work_id (replaces removed pica_recordings_by_work)
  • pica_recordings_inspect - Get recording details (sections-based)
  • pica_recordings_create - Create new recording
  • pica_recordings_update - Update recording
  • pica_recordings_delete - Delete recording

Search & Analytics (2 tools)

  • pica_search_all - Search across all entities
  • pica_catalog_stats - Get catalog statistics

4 Data Resources

Read-only access to catalog data:

  • works://list - All works
  • people://list - All people
  • recordings://list - All recordings
  • catalog://stats - Catalog statistics

4 Workflow Prompts

Pre-configured prompts for common tasks:

  • analyze-catalog - Comprehensive catalog analysis
  • find-duplicates - Find duplicate entries
  • enrich-metadata - Identify enrichment opportunities
  • verify-works - Review unverified works

Installation

npm install -g @withpica/mcp-server

From Source

cd mcp-server
npm install
npm run build
npm link

Configuration

Get Your PICA API Key

  1. Log into PICA at https://withpica.com
  2. Go to Settings → API Keys
  3. Generate a new API key
  4. Copy the key for use below

Claude Desktop Setup

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "pica": {
      "command": "npx",
      "args": ["-y", "@withpica/mcp-server"],
      "env": {
        "PICA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP-Compatible AI Assistants

The setup process is similar for any MCP-compatible tool:

  1. Configure the MCP server command: npx -y @withpica/mcp-server
  2. Set the PICA_API_KEY environment variable
  3. The AI can now access all PICA tools and resources

Usage Examples

Example 1: List Your Works

User: "Show me my musical works"

AI uses: pica_works_list

Result: List of works with titles, ISWCs, verification status, etc.

Example 2: Create a Work

User: "Create a new composition called 'Moonlight Sonata No. 2'"

AI uses: pica_works_create with appropriate parameters

Result: New work created with generated ID

Example 3: Analyze Catalog

User: "Analyze my catalog"

AI uses: analyze-catalog prompt

AI calls:

  • pica_catalog_stats - Get statistics
  • pica_works_list - Review works
  • pica_people_list - Review people

Result: Comprehensive analysis with insights and recommendations

Example 4: Find Duplicates

User: "Find duplicate entries"

AI uses: find-duplicates prompt

AI calls:

  • pica_works_list - Get all works
  • pica_people_list - Get all people

Result: List of potential duplicates with merge recommendations

Example 5: Enrich Metadata

User: "Enrich Mozart's profile from ISNI"

AI uses: pica_people_enrich_isni with person ID and ISNI

Result: Person record updated with enriched data from ISNI

Use Cases

For Catalog Managers

  • "Show me all unverified works"
  • "Find duplicate entries"
  • "List works missing ISWC codes"
  • "Enrich all people from ISNI"

For Data Analysis

  • "What's the average duration of my compositions?"
  • "Who are my most prolific composers?"
  • "Which works have the most recordings?"
  • "Show me catalog statistics"

For Enrichment

  • "Find all people that could be enriched from MusicBrainz"
  • "Suggest ISNI matches for unverified artists"
  • "Which works are missing metadata?"

For Bulk Operations

  • "Create works from this list"
  • "Verify all completed works"
  • "Delete test entries"

Environment Variables

  • PICA_API_KEY (required) - Your PICA API key
  • PICA_API_URL (optional) - API base URL (default: https://withpica.com/api)
  • DEBUG (optional) - Enable debug logging (set to 'true' or '1')

Development

Build

npm run build

Development Mode

npm run dev

Local Testing

PICA_API_KEY=your-key npm run dev

Troubleshooting

"PICA_API_KEY environment variable is required"

Make sure you've set the API key in your MCP server configuration:

{
  "env": {
    "PICA_API_KEY": "your-actual-api-key"
  }
}

"Authentication failed"

  • Verify your API key is correct
  • Check that the API key hasn't been revoked
  • Generate a new API key if needed

Tools Not Showing Up

  1. Restart your AI assistant after configuring the MCP server
  2. Check the MCP server logs for errors
  3. Verify the configuration file syntax is correct

Connection Issues

  • Ensure you have an internet connection
  • Check that https://withpica.com is accessible
  • Verify no firewall is blocking the connection

Architecture

MCP Server for PICA
├── Protocol Handler (MCP standard)
├── Authentication (API key)
├── Tools (24 AI-callable functions)
│   ├── Works Management (8)
│   ├── People Management (8)
│   ├── Recordings Management (6)
│   └── Search & Analytics (2)
├── Resources (4 data providers)
└── Prompts (4 workflows)

Security

  • All requests require a valid PICA API key
  • API keys are transmitted securely over HTTPS
  • Data access is scoped to your organization
  • No data is stored by the MCP server

Support

License

MIT

Credits

Built with:

Server Config

{
  "mcpServers": {
    "withpica": {
      "command": "npx",
      "args": [
        "--yes",
        "@withpica/mcp-server@latest"
      ]
    }
  }
}
Project Info
Created At
2 months ago
Updated At
a month ago
Author Name
withpica
Star
-
Language
-
License
-
Category

Recommend Servers

View All
GovQL
@Alex Stout

# govql-mcp-server An MCP (Model Context Protocol) server for [GovQL](https://govql.us) — gives AI clients like Claude Desktop, Claude Code, and Cursor direct access to the US Congressional GraphQL API at [api.govql.us/graphql](https://api.govql.us/graphql) without bespoke HTTP wiring. For the design rationale (why FastMCP-Python, the passthrough+curated philosophy, roadmap through v0.4), see [design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md). ## What you can do with it Ask an agent questions like: - *"How did Vermont's two senators vote on the most recent nomination?"* - *"Which legislators in the 118th Congress switched parties during their service?"* - *"Compare Senator Sanders' voting record to Senator Murkowski's on cloture votes in the most recent Congress."* The agent picks the right tool, writes the GraphQL query against the live schema, and parses the response — no manual API wrangling. ## Install The server runs as a per-client subprocess over stdio. Pick your client: ### Claude Desktop Edit `claude_desktop_config.json` (Settings → Developer → Edit Config): ```json { "mcpServers": { "govql": { "command": "uvx", "args": ["govql-mcp-server"] } } } ``` Restart Claude Desktop. The `govql` tools appear in the tools panel. ### Claude Code Add to `.mcp.json` in your project (or `~/.mcp.json` for global): ```json { "mcpServers": { "govql": { "command": "uvx", "args": ["govql-mcp-server"] } } } ``` ### Cursor Settings → MCP → Add Server. Use the same `command` / `args` as above. ### Other clients Any MCP-compatible client that supports stdio servers will work. The command is `uvx govql-mcp-server` with no required arguments. ## Tools | Tool | Purpose | |---|---| | `execute_graphql` | Run any GraphQL query against the GovQL endpoint. Returns the result plus an `last_ingest` timestamp so the agent can reason about data freshness. | | `list_types` | Returns the names and kinds of every type in the GovQL schema. Optional `kind` filter (`"OBJECT"`, `"INPUT_OBJECT"`, `"ENUM"`, etc.) to narrow further. Start here when you don't know what's queryable. | | `describe_type` | Returns one type's full details — fields, arg signatures, input fields, enum values. Call after `list_types` to learn the shape of a specific type before writing a query. | ## Configuration All env vars are optional — the package is zero-config for end users. | Env var | Default | Purpose | |---|---|---| | `GOVQL_ENDPOINT` | `https://api.govql.us/graphql` | Endpoint to query. Override to point at a local dev stack. | | `GOVQL_TIMEOUT_MS` | `30000` | Per-request HTTP timeout. | | `LOG_LEVEL` | `INFO` | Logging level. Logs go to stderr only (stdout is reserved for the MCP transport). | ## Limits (enforced by the upstream API) - Max query depth: 10 - Max query complexity: ~10 billion points (`first: N` multiplies child cost by N — keep page sizes reasonable on deeply nested queries) - Rate limit: 100 requests / 60 s per source IP A depth or complexity violation surfaces as a GraphQL `errors` entry in the tool response so the agent can adjust and retry. ## Data freshness Every `execute_graphql` response includes a `last_ingest` ISO timestamp. Vote data refreshes hourly; legislator data refreshes daily. ## Status Version 0.1.0 ships three foundational tools: a GraphQL passthrough (`execute_graphql`) and two narrow schema-discovery tools (`list_types`, `describe_type`). Curated higher-level tools (`find_legislator`, `get_voting_record`, `compare_voters`, etc.) are planned for subsequent releases — see [design.md](https://github.com/govql/govql/blob/main/mcp-server/docs/design.md) for the roadmap. ## Links - [GovQL project site](https://govql.us) - [GraphQL API](https://api.govql.us/graphql) - [Source / issues](https://github.com/govql/govql)

a day ago