Dolphin MCP is a flexible Python library and command-line tool for interacting with MCP (Model Context Protocol) servers through natural language. It can connect to any number of configured MCP servers, provide their tools to language models (OpenAI, Anthropic, Ollama, LMStudio), and offer a conversational interface to access and manipulate data in these servers.

Key Capabilities

Multi-provider support: Compatible with OpenAI, Anthropic, Ollama, and LMStudio models.
Modular architecture: Modules are separated by provider, with clear responsibilities.
Dual interface: Can be used both as a Python library and as a command-line tool.
MCP server integration: Can connect to any number of MCP servers simultaneously.
Tool discovery: Automatically discovers and uses tools provided by MCP servers.
Flexible configuration: Configure models and servers via JSON.
Environment variable support: Securely store API keys in environment variables.
Detailed documentation: Provides detailed usage examples and API documentation.
Installable package: Install via pip, providing the dolphin-mcp-cli command.

Installation Prerequisites

Requires Python 3.10+, SQLite (a lightweight database for demos), uv/uvx (a fast Python package installer and resolver). See the official documentation for installation methods on each platform.

Installation Methods

Method 1: Install from PyPI (recommended), which installs both the library and the dolphin-mcp-cli command-line tool. Method 2: Install from source:

git clone https://github.com/QuixiAI/dolphin-mcp.git
cd dolphin-mcp
pip install -e .

Set environment variables: Copy the example file and add the OpenAI API key:

cp .env.example .env

Then edit the .env file to add the OpenAI API key. (Optional) Set up the demo dolphin database:python setup_db.py, create a sample SQLite database containing dolphin information for testing.

Configuration

The project uses two main configuration files:

.env: Contains the OpenAI API configuration:

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o
# OPENAI_BASE_URL=https://api.openai.com/v1  # 如使用自定义 base url 可取消注释并修改

mcp_config.json: Defines the MCP servers to connect to:

{
  "mcpServers": {
    "server1": {
      "command": "command-to-start-server",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR1": "value1",
        "ENV_VAR2": "value2"
      }
    },
    "server2": {
      "command": "another-server-command",
      "args": ["--option", "value"]
    }
  }
}

You can add any number of MCP servers as needed, and the client will connect to all servers and make their tools available.

Usage

Command-line usage: run the CLI command with the query as an argument, supporting various command-line options. Interactive chat mode: start with the --interactive or -i flag, you can provide an initial question, the conversation maintains context, and entering exit or quit ends the session. Programmatic use as a library: you can import Dolphin MCP as a library in Python code. Original script (legacy): the original script can still be run directly.

How It Works

Connect to all configured MCP servers.
List the tools available on each server.
Send the user query together with the available tools to the language model API.
Execute any tool calls requested by the model.
Return the results in conversation format. This process continues until the model has all the information needed to provide a final reply.

Example Queries

Examples depend on the configured MCP servers. You can use the demo dolphin database, a custom MCP server, or specify a model. You can also use the LMStudio provider, or suppress intermediate result output via options. See the examples README for more examples.

Demo Database

Running setup_db.py creates a sample SQLite database containing dolphin species information, used to demonstrate how the system works with a simple MCP server. The database contains: information on various dolphin species, evolutionary relationships between species, conservation status, and physical characteristics. This is just an example of the Dolphin MCP client, which can connect to any MCP server that provides tools for accessing data or services.

Dependencies

Requires an OpenAI API key (or an API key for another supported provider). Core dependencies, development dependencies, and demo dependencies (mcp-server-sqlite) are installed automatically when installing with pip.

Package Structure

dolphin_mcp/: main package directory
- init.py: package initialization and exports
- client.py: core MCPClient implementation and run_interaction function
- cli.py: command-line interface
- utils.py: configuration and argument parsing utility functions
- providers/: provider-specific implementations
  - openai.py: OpenAI API integration
  - anthropic.py: Anthropic API integration
  - ollama.py: Ollama API integration
  - lmstudio.py: LMStudio SDK integration

Limitations

Specific fees, pricing, and other such information are not yet provided.

dolphin-mcp

About this tool