mcp-nullbr

This MCP server implements the NullBR API as an MCP-enabled service using SSE (server-sent events) streaming. It exposes a suite of tools to search and retrieve media information, including movies, TV shows, seasons, episodes, and people, as well as a variety of downloadable or streaming resources and CMS transfer actions. Clients can invoke functions such as searchMedia, getMovieInfo, getTVInfo, getTVSeasonInfo, getTVEpisodeInfo, getPersonInfo, getCollectionInfo, and corresponding resource endpoints like getMovieResources, getTVResources, getTVSeasonResources, getTVEpisodeResources, getPersonResources, and getCollectionResources. A dedicated addShareDown tool is also provided to transfer 115 links into a CMS. The server is built on Spring AI and communicates through the MCP protocol so it can be used with MCP-capable assistants (e.g., Claude, Cursor, Cherry Studio) to query and fetch media data, or push results into your CMS via the specified APIs. To connect from a client, configure an MCP client to point at the server’s SSE endpoint (default /sse) and enable Tool Function Calling if required by your workflow. Examples of client usage include asking the agent to search for a movie, fetch details for a TV series, or save an 115 link to the CMS, with the server returning structured results and streaming updates as available.

Prerequisites:

• JDK 17 or newer
• Maven 3.6+ (for building the project)
• Internet access to fetch dependencies

Installation steps:

1. Clone the repository

   • git clone https://github.com/yourusername/mcp-nullbr-server
   • cd mcp-nullbr-server

2. Configure credentials and CMS settings

   • Create or edit src/main/resources/application.yml and fill in API and CMS details, for example:

     nullbr: api: base-url: https://api.nullbr.eu.org app-id: YOUR_APP_ID api-key: YOUR_API_KEY

     cms: base-url: YOUR_CMS_URL username: YOUR_CMS_USERNAME password: YOUR_CMS_PASSWORD

   • These values will be read by the Java application at startup. You may also set corresponding environment variables if preferred.

3. Build the project

   • mvn clean package

4. Run the server

   • java -jar target/mcp-nullbr-server-0.0.1-SNAPSHOT.jar

5. Verify the service

   • Open http://localhost:8080/sse to ensure the SSE endpoint is serving events, and test with a MCP client using the proper server URL.

Notes:

• If you change the server port, update your MCP client configuration accordingly.
• Ensure network access to the configured NullBR API and CMS endpoints from the running server.

Environment variables (optional) you may use to configure at runtime:

• NULLBR_API_BASE_URL: Base URL for NullBR API
• NULLBR_APP_ID: NullBR App ID
• NULLBR_API_KEY: NullBR API key
• CMS_BASE_URL: CMS base URL
• CMS_USERNAME: CMS username
• CMS_PASSWORD: CMS password

Common issues:

• If the server fails to start due to configuration errors, check src/main/resources/application.yml for correct YAML syntax and valid credentials.
• For streaming responses, ensure your MCP client supports SSE and handles chunks as they arrive.
• When deploying remotely, adjust the client URL in the MCP configuration to the server’s public address.

Compatibility:

• This is a Java-based MCP server (Spring AI). If you intend to run via other runtimes, ensure the Java runtime and Maven are available at build/run time.