Skip to content
Back to search

dolphin-mcp

A flexible Python library and CLI tool for interacting with Model Context Protocol (MCP) servers using any LLM model.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/quixiai--dolphin-mcp/badge.svg)](/listings/quixiai--dolphin-mcp)

HTML

<a href="/listings/quixiai--dolphin-mcp"><img src="/api/listings/quixiai--dolphin-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: Install from PyPI (Recommended)

pip install dolphin-mcp

This will install both the library and the `dolphin-mcp-cli` command-line tool.

Option 2: Install from Source

1. Clone this repository:

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

2. Install the package in development mode:

   pip install -e .

3. Set up your environment variables by copying the example file and adding your OpenAI API key:

   cp .env.example .env

Then edit the `.env` file to add your OpenAI API key.

4. (Optional) Set up the demo dolphin database:

   python setup_db.py

This creates a sample SQLite database with dolphin information that you can use to test the system.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 361 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Dolphin MCP
  2. A flexible Python library and CLI tool for interacting with Model Context Protocol (MCP) servers using any LLM model.
  3. ![image](https://github.com/user-attachments/assets/d0ee1159-2a8f-454d-8fba-cf692f425af9)
  4. ## Overview
  5. Dolphin MCP is both a Python library and a command-line tool that allows you to query and interact with MCP servers through natural language. It connects to any number of configured MCP servers, makes their tools available to language models (OpenAI, Anthropic, Ollama, LMStudio), and provides a conversational interface for accessing and manipulating data from these servers.
  6. The project demonstrates how to:
  7. - Connect to multiple MCP servers simultaneously
  8. - List and call tools provided by these servers
  9. - Use function calling capabilities to interact with external data sources
  10. - Process and present results in a user-friendly way
  11. - Create a reusable Python library with a clean API
  12. - Build a command-line interface on top of the library
  13. ## Features
  14. - **Multiple Provider Support**: Works with OpenAI, Anthropic, Ollama, and LMStudio models
  15. - **Modular Architecture**: Clean separation of concerns with provider-specific modules
  16. - **Dual Interface**: Use as a Python library or command-line tool
  17. - **MCP Server Integration**: Connect to any number of MCP servers simultaneously
  18. - **Tool Discovery**: Automatically discover and use tools provided by MCP servers
  19. - **Flexible Configuration**: Configure models and servers through JSON configuration
  20. - **Environment Variable Support**: Securely store API keys in environment variables
  21. - **Comprehensive Documentation**: Detailed usage examples and API documentation
  22. - **Installable Package**: Easy installation via pip with `dolphin-mcp-cli` command
  23. ## Prerequisites
  24. Before installing Dolphin MCP, ensure you have the following prerequisites installed:
  25. 1. **Python 3.10+**
  26. 2. **SQLite** - A lightweight database used by the demo
  27. 3. **uv/uvx** - A fast Python package installer and resolver
  28. ### Setting up Prerequisites
  29. #### Windows
  30. 1. **Python 3.10+**:
  31. - Download and install from [python.org](https://www.python.org/downloads/windows/)
  32. - Ensure you check "Add Python to PATH" during installation
  33. 2. **SQLite**:
  34. - Download the precompiled binaries from [SQLite website](https://www.sqlite.org/download.html)
  35. - Choose the "Precompiled Binaries for Windows" section and download the sqlite-tools zip file
  36. - Extract the files to a folder (e.g., `C:\sqlite`)
  37. - Add this folder to your PATH:
  38. - Open Control Panel > System > Advanced System Settings > Environment Variables
  39. - Edit the PATH variable and add the path to your SQLite folder
  40. - Verify installation by opening Command Prompt and typing `sqlite3 --version`
  41. 3. **uv/uvx**:
  42. - Open PowerShell as Administrator and run:
  43. ```
  44. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  45. ```
  46. - Restart your terminal and verify installation with `uv --version`
  47. #### macOS
  48. 1. **Python 3.10+**:
  49. - Install using Homebrew:
  50. ```
  51. brew install python
  52. ```
  53. 2. **SQLite**:
  54. - SQLite comes pre-installed on macOS, but you can update it using Homebrew:
  55. ```
  56. brew install sqlite
  57. ```
  58. - Verify installation with `sqlite3 --version`
  59. 3. **uv/uvx**:
  60. - Install using Homebrew:
  61. ```
  62. brew install uv
  63. ```
  64. - Or use the official installer:
  65. ```
  66. curl -LsSf https://astral.sh/uv/install.sh | sh
  67. ```
  68. - Verify installation with `uv --version`
  69. #### Linux (Ubuntu/Debian)
  70. 1. **Python 3.10+**:
  71. ```
  72. sudo apt update
  73. sudo apt install python3 python3-pip
  74. ```
  75. 2. **SQLite**:
  76. ```
  77. sudo apt update
  78. sudo apt install sqlite3
  79. ```
  80. - Verify installation with `sqlite3 --version`
  81. 3. **uv/uvx**:
  82. ```
  83. curl -LsSf https://astral.sh/uv/install.sh | sh
  84. ```
  85. - Verify installation with `uv --version`
  86. ## Installation
  87. ### Option 1: Install from PyPI (Recommended)
  88. ```bash
  89. pip install dolphin-mcp
  90. ```
  91. This will install both the library and the `dolphin-mcp-cli` command-line tool.
  92. ### Option 2: Install from Source
  93. 1. Clone this repository:
  94. ```bash
  95. git clone https://github.com/QuixiAI/dolphin-mcp.git
  96. cd dolphin-mcp
  97. ```
  98. 2. Install the package in development mode:
  99. ```bash
  100. pip install -e .
  101. ```
  102. 3. Set up your environment variables by copying the example file and adding your OpenAI API key:
  103. ```bash
  104. cp .env.example .env
  105. ```
  106. Then edit the `.env` file to add your OpenAI API key.
  107. 4. (Optional) Set up the demo dolphin database:
  108. ```bash
  109. python setup_db.py
  110. ```
  111. This creates a sample SQLite database with dolphin information that you can use to test the system.
  112. ## Configuration
  113. The project uses two main configuration files:
  114. 1. `.env` - Contains OpenAI API configuration:
  115. ```
  116. OPENAI_API_KEY=your_openai_api_key_here
  117. OPENAI_MODEL=gpt-4o
  118. # OPENAI_BASE_URL=https://api.openai.com/v1 # Uncomment and modify if using a custom base url
  119. ```
  120. 2. `mcp_config.json` - Defines MCP servers to connect to:
  121. ```json
  122. {
  123. "mcpServers": {
  124. "server1": {
  125. "command": "command-to-start-server",
  126. "args": ["arg1", "arg2"],
  127. "env": {
  128. "ENV_VAR1": "value1",
  129. "ENV_VAR2": "value2"
  130. }
  131. },
  132. "server2": {
  133. "command": "another-server-command",
  134. "args": ["--option", "value"]
  135. }
  136. }
  137. }
  138. ```
  139. You can add as many MCP servers as you need, and the client will connect to all of them and make their tools available.
  140. ## Usage
  141. ### Using the CLI Command
  142. Run the CLI command with your query as an argument:
  143. ```bash
  144. dolphin-mcp-cli "Your query here"
  145. ```
  146. ### Command-line Options
  147. ```
  148. Usage: dolphin-mcp-cli [--model <name>] [--quiet] [--interactive | -i] [--config <file>] [--mcp-config <file>] [--log-messages <file>] [--debug] ['your question']
  149. Options:
  150. --model <name> Specify the model to use (e.g., gpt-4o, dolphin, qwen2.5-7b)
  151. --quiet Suppress intermediate output (except errors)
  152. --interactive, -i Enable interactive chat mode. If selected, 'your question' argument is optional for the first turn.
  153. --config <file> Specify a custom config file for LLM providers (default: config.yml)
  154. --mcp-config <file> Specify a custom config file for MCP servers (default: examples/sqlite-mcp.json)
  155. --log-messages <file> Log all LLM interactions to a JSONL file
  156. --debug Enable debug logging (Note: `cli.py` sets DEBUG level by default currently)
  157. --help, -h Show this help message
  158. ```
  159. ### Interactive Chat Mode
  160. To start `dolphin-mcp-cli` in interactive mode, use the `--interactive` or `-i` flag:
  161. ```bash
  162. dolphin-mcp-cli --interactive
  163. # or
  164. dolphin-mcp-cli -i
  165. ```
  166. You can also provide an initial question:
  167. ```bash
  168. dolphin-mcp-cli -i "What dolphin species are endangered?"
  169. ```
  170. In interactive mode, you can have a continuous conversation with the configured model. The chat will maintain context from previous turns. Type `exit` or `quit` to end the session.
  171. ### Using the Library Programmatically
  172. You can also use Dolphin MCP as a library in your Python code:
  173. ```python
  174. import asyncio
  175. from dolphin_mcp import run_interaction
  176. async def main():
  177. result = await run_interaction(
  178. user_query="What dolphin species are endangered?",
  179. model_name="gpt-4o", # Optional, will use default from config if not specified
  180. config_path="mcp_config.json", # Optional, defaults to mcp_config.json
  181. quiet_mode=False # Optional, defaults to False
  182. )
  183. print(result)
  184. # Run the async function
  185. asyncio.run(main())
  186. ```
  187. ### Using the Original Script (Legacy)
  188. You can still run the original script directly:
  189. ```bash
  190. python dolphin_mcp.py "Your query here"
  191. ```
  192. The tool will:
  193. 1. Connect to all configured MCP servers
  194. 2. List available tools from each server
  195. 3. Call the language model API with your query and the available tools
  196. 4. Execute any tool calls requested by the model
  197. 5. Return the results in a conversational format
  198. ## Example Queries
  199. Examples will depend on the MCP servers you have configured. With the demo dolphin database:
  200. ```bash
  201. dolphin-mcp-cli --mcp-config examples/sqlite-mcp.json --model gpt-4o "What dolphin species are endangered?"
  202. ```
  203. Or with your own custom MCP servers:
  204. ```bash
  205. dolphin-mcp-cli "Query relevant to your configured servers"
  206. ```
  207. You can also specify a model to use:
  208. ```bash
  209. dolphin-mcp-cli --model gpt-4o "What are the evolutionary relationships between dolphin species?"
  210. ```
  211. To use the LMStudio provider:
  212. ```bash
  213. dolphin-mcp-cli --model qwen2.5-7b "What are the evolutionary relationships between dolphin species?"
  214. ```
  215. For quieter output (suppressing intermediate results):
  216. ```bash
  217. dolphin-mcp-cli --quiet "List all dolphin species in the Atlantic Ocean"
  218. ```
  219. For more detailed examples and use cases, please refer to the [examples README](./examples/README.md).
  220. ## Demo Database
  221. If you run `setup_db.py`, it will create a sample SQLite database with information about dolphin species. This is provided as a demonstration of how the system works with a simple MCP server. The database includes:
  222. - Information about various dolphin species
  223. - Evolutionary relationships between species
  224. - Conservation status and physical characteristics
  225. This is just one example of what you can do with the Dolphin MCP client. You can connect it to any MCP server that provides tools for accessing different types of data or services.
  226. ## Requirements
  227. - Python 3.10+
  228. - OpenAI API key (or other supported provider API keys)
  229. ### Core Dependencies
  230. - openai
  231. - mcp[cli]
  232. - python-dotenv
  233. - anthropic
  234. - ollama
  235. - lmstudio
  236. - jsonschema
  237. ### Development Dependencies
  238. - pytest
  239. - pytest-asyncio
  240. - pytest-mock
  241. - uv
  242. ### Demo Dependencies
  243. - mcp-server-sqlite
  244. All dependencies are automatically installed when you install the package using pip.
  245. ## How It Works
  246. ### Package Structure
  247. The package is organized into several modules:
  248. - `dolphin_mcp/` - Main package directory
  249. - `__init__.py` - Package initialization and exports
  250. - `client.py` - Core MCPClient implementation and run_interaction function
  251. - `cli.py` - Command-line interface
  252. - `utils.py` - Utility functions for configuration and argument parsing
  253. - `providers/` - Provider-specific implementations
  254. - `openai.py` - OpenAI API integration
  255. - `anthropic.py` - Anthropic API integration
  256. - `ollama.py` - Ollama API integration
  257. - `lmstudio.py` - LMStudio SDK integration
  258. ### Execution Flow
  259. 1. The CLI parses command-line arguments and calls the library's `run_interaction` function.
  260. 2. The library loads configuration from `mcp_config.json` and connects to each configured MCP server.
  261. 3. It retrieves the list of available tools from each server and formats them for the language model's API.
  262. 4. The user's query is sent to the selected language model (OpenAI, Anthropic, Ollama, or LMStudio) along with the available tools.
  263. 5. If the model decides to call a tool, the library routes the call to the appropriate server and returns the result.
  264. 6. This process continues until the model has all the information it needs to provide a final response.
  265. This modular architecture allows for great flexibility - you can add any MCP server that provides tools for accessing different data sources or services, and the client will automatically make those tools available to the language model. The provider-specific modules also make it easy to add support for additional language model providers in the future.
  266. ## Contributing
  267. Contributions are welcome! Please feel free to submit a Pull Request.
  268. ## License
  269. [Add your license information here]

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.