Skip to content
Back to search

mcphub

MCPHub is an embeddable Model Context Protocol (MCP) solution for AI services. Seamlessly integrate MCP servers with OpenAI Agents, LangChain, and Autogen frameworks through a unified interface. Simplifies configuration, setup, and management of MCP tools across different AI applications.

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/cognitive-stack--mcphub/badge.svg)](/listings/cognitive-stack--mcphub)

HTML

<a href="/listings/cognitive-stack--mcphub"><img src="/api/listings/cognitive-stack--mcphub/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.

These steps run a script from the network that findsafeskills does not scan.

Prerequisites

Ensure you have the following tools installed:

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install git (for repository cloning)
sudo apt-get install git  # Ubuntu/Debian
brew install git         # macOS

# Install npx (comes with Node.js)
npm install -g npx

# Install MCPHub
pip install mcphub  # Basic installation

# Optional: Install with framework-specific dependencies
pip install mcphub[openai]    # For OpenAI Agents integration
pip install mcphub[langchain] # For LangChain integration
pip install mcphub[autogen]   # For Autogen integration
pip install mcphub[all]       # Install all optional dependencies

Configuration

Create a `.mcphub.json` file in your project root:

{
    "mcpServers": {
        "sequential-thinking-mcp": {
            "package_name": "smithery-ai/server-sequential-thinking",
            "command": "npx",
            "args": [
                "-y",
                "@smithery/cli@latest",
                "run",
                "@smithery-ai/server-sequential-thinking"
            ]
        }
    }
}

Adding New MCP Servers

You can add new MCP servers in two ways:

1. **Manual Configuration**: Add the server configuration directly to your `.mcphub.json` file.

2. **Automatic Configuration from GitHub**: Use the `add_server_from_repo` method to automatically configure a server from its GitHub repository:

from mcphub import MCPHub

# Initialize MCPHub
hub = MCPHub()

# Add a new server from GitHub
hub.servers_params.add_server_from_repo(
    server_name="my-server",
    repo_url="https://github.com/username/repo"
)

The automatic configuration: - Fetches the README from the GitHub repository - Uses OpenAI to analyze the README and extract the server configuration - Adds the configuration to your `.mcphub.json` file - Requires an OpenAI API key (set via `OPENAI_API_KEY` environment variable)

Usage with OpenAI Agents

import asyncio
import json
from agents import Agent, Runner
from mcphub import MCPHub

async def main():
    """
    Example of using MCPHub to integrate MCP servers with OpenAI Agents.

    This example demonstrates:
    1. Initializing MCPHub
    2. Fetching and using an MCP server
    3. Listing available tools
    4. Creating and running an agent with MCP tools
    """

    # Step 1: Initialize MCPHub
    # MCPHub will automatically:
    # - Find .mcphub.json in your project
    # - Load server configurations
    # - Set up servers (clone repos, run setup scripts if needed)
    hub = MCPHub()

    # Step 2: Create an MCP server instance using async context manager
    # Parameters:
    # - mcp_name: The name of the server from your .mcphub.json
    # - cache_tools_list: Cache the tools list for better performance
    async with hub.fetch_openai_mcp_server(
        mcp_name="sequential-thinking-mcp",
        cache_tools_list=True
    ) as server:
        # Step 3: List available tools from the MCP server
        # This shows what capabilities are available to your agent
        tools = await server.list_tools()

        # Pretty print the tools for better readability
        tools_dict = [
            dict(tool) if hasattr(tool, "__dict__") else tool for tool in tools
        ]
        print("Available MCP Tools:")
        print(json.dumps(tools_dict, indent=2))

        # Step 4: Create an OpenAI Agent with MCP server
        # The agent can now use all tools provided by the MCP server
        agent = Agent(
            name="Assistant",
            instructions="Use the available tools to accomplish the given task",
            mcp_servers=[server]  # Provide the MCP server to the agent
        )

        # Step 5: Run your agent with a complex task
        # The agent will automatically have access to all MCP tools
        complex_task = """Please help me analyze the following complex problem: 

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 · 422 lines

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

  1. # MCPHub
  2. MCPHub is an embeddable Model Context Protocol (MCP) solution for AI services. It enables seamless integration of MCP servers into any AI framework, allowing developers to easily configure, set up, and manage MCP servers within their applications. Whether you're using OpenAI Agents, LangChain, or Autogen, MCPHub provides a unified way to connect your AI services with MCP tools and resources.
  3. ## Documentation
  4. - [CLI Documentation](src/mcphub/cli/README.md) - Command-line interface for managing MCP servers
  5. - [API Documentation](docs/api.md) - Python API reference
  6. - [Configuration Guide](docs/configuration.md) - Server configuration details
  7. - [Examples](docs/examples.md) - Usage examples and tutorials
  8. ## Quick Start
  9. ### Prerequisites
  10. Ensure you have the following tools installed:
  11. ```bash
  12. # Install uv (Python package manager)
  13. curl -LsSf https://astral.sh/uv/install.sh | sh
  14. # Install git (for repository cloning)
  15. sudo apt-get install git # Ubuntu/Debian
  16. brew install git # macOS
  17. # Install npx (comes with Node.js)
  18. npm install -g npx
  19. # Install MCPHub
  20. pip install mcphub # Basic installation
  21. # Optional: Install with framework-specific dependencies
  22. pip install mcphub[openai] # For OpenAI Agents integration
  23. pip install mcphub[langchain] # For LangChain integration
  24. pip install mcphub[autogen] # For Autogen integration
  25. pip install mcphub[all] # Install all optional dependencies
  26. ```
  27. ### Configuration
  28. Create a `.mcphub.json` file in your project root:
  29. ```json
  30. {
  31. "mcpServers": {
  32. "sequential-thinking-mcp": {
  33. "package_name": "smithery-ai/server-sequential-thinking",
  34. "command": "npx",
  35. "args": [
  36. "-y",
  37. "@smithery/cli@latest",
  38. "run",
  39. "@smithery-ai/server-sequential-thinking"
  40. ]
  41. }
  42. }
  43. }
  44. ```
  45. ### Adding New MCP Servers
  46. You can add new MCP servers in two ways:
  47. 1. **Manual Configuration**: Add the server configuration directly to your `.mcphub.json` file.
  48. 2. **Automatic Configuration from GitHub**: Use the `add_server_from_repo` method to automatically configure a server from its GitHub repository:
  49. ```python
  50. from mcphub import MCPHub
  51. # Initialize MCPHub
  52. hub = MCPHub()
  53. # Add a new server from GitHub
  54. hub.servers_params.add_server_from_repo(
  55. server_name="my-server",
  56. repo_url="https://github.com/username/repo"
  57. )
  58. ```
  59. The automatic configuration:
  60. - Fetches the README from the GitHub repository
  61. - Uses OpenAI to analyze the README and extract the server configuration
  62. - Adds the configuration to your `.mcphub.json` file
  63. - Requires an OpenAI API key (set via `OPENAI_API_KEY` environment variable)
  64. ### Usage with OpenAI Agents
  65. ```python
  66. import asyncio
  67. import json
  68. from agents import Agent, Runner
  69. from mcphub import MCPHub
  70. async def main():
  71. """
  72. Example of using MCPHub to integrate MCP servers with OpenAI Agents.
  73. This example demonstrates:
  74. 1. Initializing MCPHub
  75. 2. Fetching and using an MCP server
  76. 3. Listing available tools
  77. 4. Creating and running an agent with MCP tools
  78. """
  79. # Step 1: Initialize MCPHub
  80. # MCPHub will automatically:
  81. # - Find .mcphub.json in your project
  82. # - Load server configurations
  83. # - Set up servers (clone repos, run setup scripts if needed)
  84. hub = MCPHub()
  85. # Step 2: Create an MCP server instance using async context manager
  86. # Parameters:
  87. # - mcp_name: The name of the server from your .mcphub.json
  88. # - cache_tools_list: Cache the tools list for better performance
  89. async with hub.fetch_openai_mcp_server(
  90. mcp_name="sequential-thinking-mcp",
  91. cache_tools_list=True
  92. ) as server:
  93. # Step 3: List available tools from the MCP server
  94. # This shows what capabilities are available to your agent
  95. tools = await server.list_tools()
  96. # Pretty print the tools for better readability
  97. tools_dict = [
  98. dict(tool) if hasattr(tool, "__dict__") else tool for tool in tools
  99. ]
  100. print("Available MCP Tools:")
  101. print(json.dumps(tools_dict, indent=2))
  102. # Step 4: Create an OpenAI Agent with MCP server
  103. # The agent can now use all tools provided by the MCP server
  104. agent = Agent(
  105. name="Assistant",
  106. instructions="Use the available tools to accomplish the given task",
  107. mcp_servers=[server] # Provide the MCP server to the agent
  108. )
  109. # Step 5: Run your agent with a complex task
  110. # The agent will automatically have access to all MCP tools
  111. complex_task = """Please help me analyze the following complex problem:
  112. We need to design a new feature for our product that balances user privacy
  113. with data collection for improving the service. Consider the ethical implications,
  114. technical feasibility, and business impact. Break down your thinking process
  115. step by step, and provide a detailed recommendation with clear justification
  116. for each decision point."""
  117. # Execute the task and get the result
  118. result = await Runner.run(agent, complex_task)
  119. print("\nAgent Response:")
  120. print(result)
  121. if __name__ == "__main__":
  122. # Run the async main function
  123. asyncio.run(main())
  124. ```
  125. ## Features and Guidelines
  126. ### Server Configuration
  127. - **JSON-based Configuration**: Simple `.mcphub.json` configuration file
  128. - **Environment Variable Support**: Use environment variables in configuration
  129. - **Predefined Servers**: Access to a growing list of pre-configured MCP servers
  130. - **Custom Server Support**: Easy integration of custom MCP servers
  131. Configure your MCP servers in `.mcphub.json`:
  132. ```json
  133. {
  134. "mcpServers": {
  135. // TypeScript-based MCP server using NPX
  136. "sequential-thinking-mcp": {
  137. "package_name": "smithery-ai/server-sequential-thinking", // NPM package name
  138. "command": "npx", // Command to run server
  139. "args": [ // Command arguments
  140. "-y",
  141. "@smithery/cli@latest",
  142. "run",
  143. "@smithery-ai/server-sequential-thinking"
  144. ]
  145. },
  146. // Python-based MCP server from GitHub
  147. "azure-storage-mcp": {
  148. "package_name": "mashriram/azure_mcp_server", // Package identifier
  149. "repo_url": "https://github.com/mashriram/azure_mcp_server", // GitHub repository
  150. "command": "uv", // Python package manager
  151. "args": ["run", "mcp_server_azure_cmd"], // Run command
  152. "setup_script": "uv pip install -e .", // Installation script
  153. "env": { // Environment variables
  154. "AZURE_STORAGE_CONNECTION_STRING": "${AZURE_STORAGE_CONNECTION_STRING}",
  155. "AZURE_STORAGE_CONTAINER_NAME": "${AZURE_STORAGE_CONTAINER_NAME}",
  156. "AZURE_STORAGE_BLOB_NAME": "${AZURE_STORAGE_BLOB_NAME}"
  157. }
  158. }
  159. }
  160. }
  161. ```
  162. ### MCP Server Installation and Management
  163. - **Flexible Server Setup**: Supports both TypeScript and Python-based MCP servers
  164. - **Multiple Installation Sources**:
  165. - NPM packages via `npx`
  166. - Python packages via GitHub repository URLs
  167. - Local development servers
  168. - **Automatic Setup**: Handles repository cloning, dependency installation, and server initialization
  169. ### Transport Support
  170. - **stdio Transport**: Run MCP servers as local subprocesses
  171. - **SSE Transport**: Run MCP servers with Server-Sent Events (SSE) support using supergateway
  172. - **Automatic Path Management**: Manages server paths and working directories
  173. - **Environment Variable Handling**: Configurable environment variables per server
  174. #### Running Servers with SSE Support
  175. You can run MCP servers with SSE support using the `mcphub run` command:
  176. ```bash
  177. # Basic usage with default settings
  178. mcphub run your-server-name --sse
  179. # Advanced usage with custom settings
  180. mcphub run your-server-name --sse \
  181. --port 8000 \
  182. --base-url http://localhost:8000 \
  183. --sse-path /sse \
  184. --message-path /message
  185. ```
  186. SSE support is useful when you need to:
  187. - Connect to MCP servers from web applications
  188. - Use real-time communication with MCP servers
  189. - Integrate with clients that support SSE
  190. The SSE server provides two endpoints:
  191. - `/sse`: SSE endpoint for real-time updates
  192. - `/message`: HTTP endpoint for sending messages
  193. Example configuration in `.mcphub.json`:
  194. ```json
  195. {
  196. "mcpServers": {
  197. "sequential-thinking-mcp": {
  198. "package_name": "smithery-ai/server-sequential-thinking",
  199. "command": "npx",
  200. "args": [
  201. "-y",
  202. "@smithery/cli@latest",
  203. "run",
  204. "@smithery-ai/server-sequential-thinking",
  205. "--key",
  206. "your-api-key"
  207. ]
  208. }
  209. }
  210. }
  211. ```
  212. ### Framework Integration
  213. Provides adapters for popular AI frameworks:
  214. - OpenAI Agents ([example](examples/with_openai.py))
  215. - LangChain ([example](examples/with_langchain.py))
  216. - Autogen ([example](examples/with_autogen.py))
  217. ```python
  218. from mcphub import MCPHub
  219. async def framework_quick_examples():
  220. hub = MCPHub()
  221. # 1. OpenAI Agents Integration
  222. async with hub.fetch_openai_mcp_server(
  223. mcp_name="sequential-thinking-mcp",
  224. cache_tools_list=True
  225. ) as server:
  226. # Use server with OpenAI agents
  227. agent = Agent(
  228. name="Assistant",
  229. mcp_servers=[server]
  230. )
  231. # 2. LangChain Tools Integration
  232. langchain_tools = await hub.fetch_langchain_mcp_tools(
  233. mcp_name="sequential-thinking-mcp",
  234. cache_tools_list=True
  235. )
  236. # Use tools with LangChain
  237. # 3. Autogen Adapters Integration
  238. autogen_adapters = await hub.fetch_autogen_mcp_adapters(
  239. mcp_name="sequential-thinking-mcp"
  240. )
  241. # Use adapters with Autogen
  242. ```
  243. ### Tool Management
  244. - **Tool Discovery**: Automatically list and manage available tools from MCP servers
  245. - **Tool Caching**: Optional caching of tool lists for improved performance
  246. - **Framework-specific Adapters**: Convert MCP tools to framework-specific formats
  247. Discover and manage MCP server tools:
  248. ```python
  249. from mcphub import MCPHub
  250. async def tool_management():
  251. hub = MCPHub()
  252. # List all servers
  253. servers = hub.list_servers()
  254. # List all tools from a specific MCP server
  255. tools = await hub.list_tools(mcp_name="sequential-thinking-mcp")
  256. # Print tool information
  257. for tool in tools:
  258. print(f"Tool Name: {tool.name}")
  259. print(f"Description: {tool.description}")
  260. print(f"Parameters: {tool.parameters}")
  261. print("---")
  262. # Tools can be:
  263. # - Cached for better performance using cache_tools_list=True
  264. # - Converted to framework-specific formats automatically
  265. # - Used directly with AI frameworks through adapters
  266. ```
  267. ## MCPHub: High-Level Overview
  268. MCPHub simplifies the integration of Model Context Protocol (MCP) servers into AI applications through four main components:
  269. ![MCPHub Architecture](./docs/simple_mcphub_work.png)
  270. ### Core Components
  271. 1. **Params Hub**
  272. - Manages configurations from `.mcphub.json`
  273. - Defines which MCP servers to use and how to set them up
  274. - Stores server parameters like commands, arguments, and environment variables
  275. 2. **MCP Servers Manager**
  276. - Handles server installation and setup
  277. - Supports two types of servers:
  278. * TypeScript-based servers (installed via npx)
  279. * Python-based servers (installed via uv from GitHub)
  280. - Manages server lifecycle and environment
  281. 3. **MCP Client**
  282. - Establishes communication with MCP servers
  283. - Uses stdio transport for server interaction
  284. - Handles two main operations:
  285. * `list_tools`: Discovers available server tools
  286. * `call_tool`: Executes server tools
  287. 4. **Framework Adapters**
  288. - Converts MCP tools to framework-specific formats
  289. - Supports multiple AI frameworks:
  290. * OpenAI Agents
  291. * LangChain
  292. * Autogen
  293. ### Workflow
  294. 1. **Configuration & Setup**
  295. - Params Hub reads configuration
  296. - Servers Manager sets up required servers
  297. - Servers start and become available
  298. 2. **Communication**
  299. - MCP Client connects to servers via stdio
  300. - Tools are discovered and made available
  301. - Requests and responses flow between client and server
  302. 3. **Integration**
  303. - Framework adapters convert MCP tools
  304. - AI applications use adapted tools through their preferred framework
  305. - Tools are executed through the established communication channel
  306. This architecture provides a seamless way to integrate MCP capabilities into any AI application while maintaining clean separation of concerns and framework flexibility.
  307. ## Development
  308. ### Testing
  309. Run the unit tests with pytest:
  310. ```bash
  311. pytest tests/ -v
  312. ```
  313. ### CI/CD Pipeline
  314. This project uses GitHub Actions for continuous integration and deployment:
  315. 1. **Automated Testing**: Tests are run on Python 3.10, 3.11, and 3.12 for every push to main and release branches and for pull requests.
  316. 2. **Automatic Version Bumping and Tagging**: When code is pushed to the `release` branch:
  317. - The patch version is automatically incremented in `pyproject.toml`
  318. - A new Git tag (e.g., `v0.1.2`) is created for the release
  319. - Changes are committed back to the repository
  320. 3. **PyPI Publishing**: When code is pushed to the `release` branch and tests pass, the package is automatically built and published to PyPI.
  321. #### Setting Up PyPI Deployment
  322. To enable automatic PyPI deployment, you need to add a PyPI API token as a GitHub Secret:
  323. 1. Generate a PyPI API token at https://pypi.org/manage/account/token/
  324. 2. Go to your GitHub repository settings → Secrets and variables → Actions
  325. 3. Add a new repository secret named `PYPI_API_TOKEN` with the token value from PyPI
  326. ## Contributing
  327. We welcome contributions! Please check out our [Contributing Guide](CONTRIBUTING.md) for guidelines on how to proceed.
  328. ## License
  329. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

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