Shaamam/movie-mcp-server

Movie MCP Server

A Model Context Protocol (MCP) server that provides movie information using the OMDB API. This server supports three different transport protocols: STDIO, SSE (Server-Sent Events), and Streamable HTTP.

Features

• Movie Information Tool: Get detailed information about movies including plot, cast, ratings, and more
• Multiple Transport Protocols: Supports STDIO, SSE, and Streamable HTTP transports
• Profile-based Configuration: Easy switching between different transport modes

Available Tools

• getMovieInfo: Retrieve comprehensive movie information by title

Configuration

Prerequisites

1. Build the project:

   ./gradlew build
   

2. The server supports three profiles:

   • stdio (default): Standard input/output communication
   • sse: Server-Sent Events over HTTP
   • streamable: Streamable HTTP transport

MCP Client Configuration

Add one of the following configurations to your MCP client configuration file:

Option 1: STDIO Transport (Recommended)

{
  "mcpServers": {
    "movie-mcp-server": {
      "type": "stdio",
      "command": "java",
      "args": [
        "-Dspring.profiles.active=stdio",
        "-jar",
        "/Users/shaama/Documents/openai-mcp-demo/movie-mcp-server/build/libs/movieserver_streamable-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Option 2: SSE Transport

{
  "mcpServers": {
    "movie-mcp-server-sse": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Start the SSE server:

java -Dspring.profiles.active=sse -jar build/libs/movieserver_streamable-0.0.1-SNAPSHOT.jar

Option 3: Streamable HTTP Transport

{
  "mcpServers": {
    "movie-mcp-server-streamable": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Start the Streamable server:

java -Dspring.profiles.active=streamable -jar build/libs/movieserver_streamable-0.0.1-SNAPSHOT.jar

Build and Development

Using Taskfile

This project includes a Taskfile for common operations:

# Build all profiles
task build

# Build specific profile
task build-stdio
task build-sse  
task build-streamable



# Run specific profile
task run-stdio
task run-sse
task run-streamable

Manual Build

# Build with specific profile
./gradlew bootJar -Pprofile=stdio
./gradlew bootJar -Pprofile=sse
./gradlew bootJar -Pprofile=streamable

# Run tests
./gradlew test

Configuration Files

• application.properties: Common configuration (default stdio profile)
• application-stdio.properties: STDIO-specific settings
• application-sse.properties: SSE-specific settings
• application-streamable.properties: Streamable HTTP-specific settings

API Configuration

The server uses the OMDB API for movie data. The API key is configured in application.properties:

movie.api.url=http://www.omdbapi.com/?apikey=
movie.api.key=dummy

Transport Protocol Details

STDIO Transport

• Best for: Direct integration with MCP clients
• Communication: Standard input/output streams
• Port: Not applicable (no HTTP server)
• Logging: File-only to avoid interference with STDIO communication

SSE Transport

• Best for: Web-based clients requiring real-time updates
• Communication: HTTP POST requests with Server-Sent Events responses
• Port: 8080
• Endpoint: /sse

Streamable HTTP Transport

• Best for: HTTP-based clients with keep-alive connections
• Communication: HTTP POST/GET requests with chunked transfer encoding
• Port: 8080
• Endpoint: /mcp
• Features: Session management, resumable connections

Example Usage

Once configured, you can use the movie tool in your MCP client:

Get information about "The Matrix"

The server will return detailed movie information including plot, cast, director, ratings, and more.

Troubleshooting

STDIO Mode

• Check the log file: ~/mcp-server-stdio.log
• Ensure no other output is written to stdout

HTTP Modes (SSE/Streamable)

• Verify the server is running: curl http://localhost:8080/actuator/health
• Check server logs for any startup errors
• Ensure port 8080 is available

Development

Integration Tests

Integration tests are disabled by default and can be run manually:

# Run specific integration test
./gradlew test --tests "McpServerStdioE2ETest"
./gradlew test --tests "McpServerSseE2ETest" 
./gradlew test --tests "McpServerStreamableE2ETest"

Movie API Testing

# Test movie info functionality
./gradlew test --tests "MovieInfoIntegrationTest"