@withpica/mcp-server

withPICA MCP Server

Model Context Protocol (MCP) server for withPICA. Enables any MCP-compatible AI assistant to interact with your withPICA 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 withPICA 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 (Recommended)

npm install -g @withpica/mcp-server

From Source

cd mcp-server
npm install
npm run build
npm link

Configuration

Get Your withPICA API Key

• Log into withPICA at https://withpica.com
• Go to Settings → API Keys
• Generate a new API key
• 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:

• Configure the MCP server command: npx -y @withpica/mcp-server
• Set the PICA_API_KEY environment variable
• The AI can now access all withPICA 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

• Restart your AI assistant after configuring the MCP server
• Check the MCP server logs for errors
• 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 withPICA
├── 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 withPICA 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

• Documentation: https://docs.withpica.com
• Issues: https://github.com/withpica/pica/issues
• Email: [e-mail]

License

MIT

Credits

Built with:

• @modelcontextprotocol/sdk - MCP SDK
• @withpica/sdk - withPICA TypeScript SDK