# Soulseek MCP Server
An MCP (Model Context Protocol) server that enables Claude to search and download music files from the Soulseek peer-to-peer network.
## Prerequisites
- Node.js 18+
- A Soulseek account (create one at [slsknet.org](http://www.slsknet.org/))
## Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd SoulseekMCP
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Configuration
Set the following environment variables:
| Variable | Required | Description |
|----------|----------|-------------|
| `SOULSEEK_USERNAME` | Yes | Your Soulseek account username |
| `SOULSEEK_PASSWORD` | Yes | Your Soulseek account password |
| `DOWNLOAD_PATH` | No | Directory for downloaded files (default: `./downloads`) |
## Usage with Claude Desktop
Add the server to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"soulseek": {
"command": "node",
"args": ["path/to/SoulseekMCP/dist/index.js"],
"env": {
"SOULSEEK_USERNAME": "your-username",
"SOULSEEK_PASSWORD": "your-password",
"DOWNLOAD_PATH": "/path/to/downloads"
}
}
}
}
```
## Available Tools
### search
Search for files on the Soulseek network.
**Parameters:**
- `query` (string, required): Search query (artist, song title, album, etc.)
- `limit` (number, optional): Maximum results to return (default: 50)
### download
Download a file from a Soulseek peer.
**Parameters:**
- `username` (string, required): Username of the peer (from search results)
- `filename` (string, required): Full file path (from search results)
### get_status
Check the connection status to the Soulseek network.
## Development
Watch mode for development:
```bash
npm run dev
```
## License
MIT
