MCP Client GUI

A JavaFX-based graphical user interface for interacting with Large Language Models through the Model Context Protocol (MCP). This application merges the functionality of a JavaFX chat interface with an MCP client, allowing users to chat with AI models that have access to MCP-enabled tools and resources.

Features

• Modern JavaFX Interface: Clean, intuitive chat interface with multiple chat sessions
• MCP Integration: Connect to Model Context Protocol servers for enhanced AI capabilities
• Ollama Support: Built-in support for Ollama language models
• Settings Management: Easy configuration of LLM models and MCP configurations
• Real-time Chat: Asynchronous message processing with thinking indicators
• Tool Execution: Visual feedback when AI uses tools through MCP

Prerequisites

• Java 21 or later
• Ollama installed and running locally
• MCP server(s) configured and available
• An mcp.json configuration file

Configuration

MCP Configuration File (mcp.json)

Create an mcp.json file to define your MCP servers. Example:

{
  "mcpServers": {
    "filesystem": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/your/mcp-server-filesystem.jar",
        "/path/to/working/directory"
      ]
    },
    "web-search": {
      "command": "python",
      "args": [
        "/path/to/mcp-server-web-search/main.py"
      ],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Application Settings

When you first run the application, click the "Settings" button to configure:

1. LLM Model: The Ollama model name (e.g., qwen3:14b)
2. MCP Config File: Path to your mcp.json file
3. Ollama Base URL: URL of your Ollama instance (default: http://localhost:11434)

Building and Running

Using Gradle

# Clone or create the project
cd mcp-client-gui

# Build the project
./gradlew build

# Run the application
./gradlew run

Creating a Distribution

# Create distribution packages
./gradlew distZip distTar

# The distributions will be created in build/distributions/

Usage

1. Start the Application: Run using ./gradlew run or execute the built JAR
2. Configure Settings: Click the "Settings" button and configure your LLM model and MCP settings
3. Create a New Chat: Click "New Chat" to start a conversation
4. Chat with AI: Type messages and interact with the AI, which can use MCP tools when needed
5. Monitor Status: The status bar shows the current state (thinking, executing tools, etc.)

Project Structure

src/main/java/com/brunorozendo/mcpclientgui/
├── McpClientGuiApp.java              # Main application class
├── controller/
│   ├── MainController.java           # Main UI controller
│   └── SettingsController.java       # Settings dialog controller
├── model/
│   ├── AppSettings.java             # Application settings model
│   ├── Chat.java                    # Chat session model
│   ├── Message.java                 # Chat message model
│   ├── McpConfig.java               # MCP configuration model
│   └── OllamaApi.java               # Ollama API models
├── service/
│   ├── McpConfigLoader.java         # MCP configuration loader
│   └── OllamaApiClient.java         # Ollama API client
├── control/
│   ├── GuiChatController.java       # Chat logic controller
│   ├── McpConnectionManager.java    # MCP connection management
│   └── SystemPromptBuilder.java     # System prompt builder
└── util/
    └── SchemaConverter.java         # MCP to Ollama schema converter

Dependencies

• JavaFX: UI framework
• MCP SDK: Model Context Protocol integration
• Jackson: JSON processing
• SLF4J + Logback: Logging
• ControlsFX: Enhanced UI controls

Logging

Logs are written to:

• Console output (INFO level and above)
• logs/mcp-client-gui.log (with rotation)

Log levels can be adjusted in src/main/resources/logback.xml.

Troubleshooting

Common Issues

1. "Not configured" message: Ensure you've set up the LLM model and MCP config file in Settings
2. Connection errors: Verify Ollama is running and accessible at the configured URL
3. MCP tool errors: Check that your MCP servers are properly configured and running
4. JavaFX issues: Ensure you're using Java 21+ with JavaFX modules

Debug Mode

To enable debug logging, modify logback.xml:

<logger name="com.brunorozendo.mcpclientgui" level="DEBUG" />
<logger name="io.modelcontextprotocol" level="DEBUG" />

License

This project builds upon the Model Context Protocol SDK and follows its licensing terms.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues or questions:

1. Check the logs for error details
2. Verify your MCP configuration
3. Ensure Ollama is running and accessible
4. Create an issue with relevant log output