Metadata-Version: 2.4
Name: mcp-marketplace
Version: 0.1.3
Summary: Open MCP Marketplace, Official OneKeyMCP Router Connection, MCP Registry, MCP client, OneKey MCP Router, MCP Tool Search of commercial MCPs
Author: deepnlp.org
Author-email: aihubadmin@126.com
Project-URL: Homepage, https://www.deepnlp.org/store/ai-agent/mcp-server
Project-URL: Repository, https://github.com/aiagenta2z/mcp-marketplace
Project-URL: Documentation, https://deepnlp.org/doc/onekey_mcp_router
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.1
Requires-Dist: logging>=0.0.1
Requires-Dist: click>=8.0.3
Provides-Extra: mcp-tool-use
Requires-Dist: python-dotenv>=1.0.1; extra == "mcp-tool-use"
Requires-Dist: fastapi>=0.115.0; extra == "mcp-tool-use"
Requires-Dist: uvicorn[standard]>=0.29.0; extra == "mcp-tool-use"
Requires-Dist: pydantic>=2.7.0; extra == "mcp-tool-use"
Requires-Dist: asyncio>=3.4.3; extra == "mcp-tool-use"
Requires-Dist: openai>=1.0.0; extra == "mcp-tool-use"
Requires-Dist: anthropic>=0.25.0; extra == "mcp-tool-use"
Requires-Dist: mcp>=1.20.0; extra == "mcp-tool-use"
Requires-Dist: mcp-marketplace>=0.0.4; extra == "mcp-tool-use"
Requires-Dist: uuid>=1.30; extra == "mcp-tool-use"
Requires-Dist: python-dotenv>=1.0.1; extra == "mcp-tool-use"
Requires-Dist: httpx>=0.27.0; extra == "mcp-tool-use"
Requires-Dist: aiofiles>=23.2.1; extra == "mcp-tool-use"
Requires-Dist: anthropic>=0.25.0; extra == "mcp-tool-use"
Requires-Dist: Jinja2>=3.1.3; extra == "mcp-tool-use"
Requires-Dist: matplotlib>=3.10.0; extra == "mcp-tool-use"
Requires-Dist: logger>=1.4; extra == "mcp-tool-use"
Requires-Dist: func_timeout>=4.3.0; extra == "mcp-tool-use"
Requires-Dist: pytz>=2025.2; extra == "mcp-tool-use"
Requires-Dist: gensim>=4.4.0; extra == "mcp-tool-use"
Requires-Dist: scikit-learn>=1.7.2; extra == "mcp-tool-use"
Requires-Dist: bs4>=0.0.2; extra == "mcp-tool-use"
Requires-Dist: redis>=7.0.0; extra == "mcp-tool-use"
Provides-Extra: onekey-mcp-router
Provides-Extra: all
Requires-Dist: mcp-marketplace[mcp_tool_use]; extra == "all"
Requires-Dist: mcp-marketplace[onekey_mcp_router]; extra == "all"

# MCP Marketplace Python SDK

MCP Marketplace Python Package is a common interface to give you access to public MCP Servers, Tools, Configurations. It supports various API endpoint (such as pulsemcp.com, deepnlp.org, etc).

[PyPI](https://www.pypi.org/project/mcp-marketplace)|[Document](http://www.deepnlp.org/doc/mcp_marketplace)|[MCP Marketplace](http://www.deepnlp.org/store/ai-agent/mcp-server)|[AI Agent Search](http://www.deepnlp.org/search/agent)|[MCP Router Ranking List](https://www.deepnlp.org/agent/rankings)

### Features

0. A Lightweight MCP Client (Like Cursor,Claude) and CLI `mcpm` for personal use and benchmarking tools/LLMs
1. Search API of MCP Tools: Users can search MCP Servers Meta Info and tools fit for mcp.json by query, such as "map", "payment", "browser use"
2. List MCP Tools API: And Allow LLM and AI Apps to Find Your MCP Server
3. Load MCP Config: Get latest mcp_config.json files
4. Development Customized API and Endpoint to Support Your Local MCP Marketplace API or Services
5. Registry: Allow Users to register the MCP Marketplace create, delete, update their MCP servers through various endpoints. (WIP)

### 0. Start MCP Client using `mcpm` CLI tool for Personal Use or Benchmark Purposes

**Installation**

You can install the command line `mcpm` tool from mcp-marketplace pypi package, and start a MCP Client using local 
`mcp_config.json` file

```
## Basic Usage MCP Index and Search
pip install mcp-marketplace

## MCPClient Supports User Defined mcp_config.json, Just Like Other Clients Cursor/Claude
pip install 'mcp-marketplace[mcp_tool_use]'

```

Install From GitHub Source
```angular2html
git clone https://github.com/aiagenta2z/mcp-marketplace
cd mcp-marketplace/python
pip install -e .

## Missing Dependency, Please report to use via issues
```

The CLI 'mcpm' will be in python path

``` 
mcpm run
mcpm run --host 0.0.0.0 --port 5000

## Use Local Config File, Go To GitHub Get the config https://github.com/aiagenta2z/mcp-marketplace

cd python/tests

mcpm run --port 5000 --config "./mcp_config_onekey.json"

mcpm run --port 5000 --config "./mcp_config.json"

```

Visit http://0.0.0.0:5000 for ChatUI
![Demo MCP Client UI](../docs/mcpm_mcp_client_ui.png)

Visit http://0.0.0.0:5000/mcp for mcp management

![Demo MCP Client Admin Console](../docs/mcpm_mcp_client_start.png)


#### Benchmark

You can also run various MCP benchmark using the rest API From the Client

| API | Description                                                                      |
| ---- |----------------------------------------------------------------------------------|
| /api/query | The endpoint which you can post the tool parameters to get the tool/call results |


**CURL Tests**

Once you started the service and run the target mcp server, you can run the tools calls through the REST API.

Let's say you want to post to server: <code>puppeteer</code> and test tools: <code>puppeteer_navigate</code> to navigate chrome to a webpage.

Endpoint: http://127.0.0.1:5000/api/query

```

curl -X POST -H "Content-Type: application/json" -d '{
    "server_id": "puppeteer",
    "tool_name": "puppeteer_navigate",
    "tool_input": {
        "url": "https://arxiv.org/list/cs/new"
    }
}' http://127.0.0.1:5000/api/query

```

Result 
```
{"success":true,"data":["Navigated to https://arxiv.org/list/cs/new"],"error":null}%
```


**REST GET/POST Request By Python/Typescript/etc**

For example, post request to MCP: amap-amap-sse, Tool: Get Weather and get local weather. You need to start mcp server 'amap-amap-sse' before running command line.

cd ./tests

```
python run_mcp_request.py

## define input_params
        input_params = {
            "server_id": "amap-amap-sse", 
            "tool_name": 'maps_weather',
            "tool_input": {
                "city": "乌鲁木齐"
            }
        }

```

Result
```
{'success': True, 'data': ['{"city":"乌鲁木齐市","forecasts":[{"date":"2025-06-30","week":"1","dayweather":"多云","nightweather":"多云","daytemp":"31","nighttemp":"20","daywind":"西北","nightwind":"西北","daypower":"1-3","nightpower":"1-3","daytemp_float":"31.0","nighttemp_float":"20.0"},{"date":"2025-07-01","week":"2","dayweather":"多云","nightweather":"多云","daytemp":"28","nighttemp":"20","daywind":"西北","nightwind":"西北","daypower":"1-3","nightpower":"1-3","daytemp_float":"28.0","nighttemp_float":"20.0"},{"date":"2025-07-02","week":"3","dayweather":"多云","nightweather":"多云","daytemp":"28","nighttemp":"20","daywind":"西北","nightwind":"西北","daypower":"1-3","nightpower":"1-3","daytemp_float":"28.0","nighttemp_float":"20.0"},{"date":"2025-07-03","week":"4","dayweather":"多云","nightweather":"晴","daytemp":"30","nighttemp":"21","daywind":"西北","nightwind":"西北","daypower":"1-3","nightpower":"1-3","daytemp_float":"30.0","nighttemp_float":"21.0"}]}'], 'error': None}
```

### Install

```
pip install mcp-marketplace

```

Dependency 

```
pip install uvicorn mcp fastapi pydantic dotenv asyncio httpx mcp_marketplace uuid aiofiles logger anthropic jinja2
```


### 1. Search API of MCP Tools

**Usage**

Example 1. Search MCP Marketplace By Query or Server ID

The server id follows the same in the github repo ${owner}/${repo}

```

import mcp_marketplace as mcpm

## endpoint: deepnlp
mcpm.set_endpoint("deepnlp")
result = mcpm.search(query="map", page_id=0, count_per_page=20, mode="dict")

print ("DEBUG: run_setup_config_deepnlp result:")
print (result)


## endpoint: pulsemcp
mcpm.set_endpoint("pulsemcp")
result2 = mcpm.search(query="map", count_per_page=20, offset=0)

print ("DEBUG: run_setup_config_pulsemcp result:")
print (result2)

```


**MCP Result**

```

{
  "q": "map",
  "limit": 50,
  "items": [
    {
        "id": "",
        "content_name": "Google Maps",
        "publisher_id": "pub-google-maps",
        "website": "https://github.com/modelcontextprotocol/servers/tree/main/src/google-maps",
        "review_cnt": "1",
        "subfield": "MAP",
        "field": "MCP SERVER",
        "rating": "5.0",
        "description": "",
        "content_tag_list": "official",
        "thumbnail_picture": "http://118.190.154.215/scripts/img/ai_service_content/b7fe82a3ab985ce1a953f7b4ad9c5e01.jpeg"
    },    
  ]
}
```


### 2. List MCP Tools API

 
Example 2. List Tools of MCP Servers  <code>list_tools</code> method


Let's choose the unique id of browser use mcp "/puppeteer/puppeteer". And we can search the MCP meta and list the tools as below.

```
    import mcp_marketplace as mcpm
        
    result_q = mcpm.search(query="browser use", mode="list", page_id=0, count_per_page=100, config_name="deepnlp")
    result_id = mcpm.search(id="/puppeteer/puppeteer", mode="list", page_id=0, count_per_page=100, config_name="deepnlp")
    tools = mcpm.list_tools(id="/puppeteer/puppeteer", config_name="deepnlp_tool")

    print (f'{result_id}')
    print (f'{tools}')
```

Example 2.1 List Batch Tools of MCP Servers  <code>list_tools_batch</code> method

Let's choose the unique id of browser use mcp "/puppeteer/puppeteer". And we can search the MCP meta and list the tools as below.

```
    import mcp_marketplace as mcpm
        
    servers_ids = ["puppeteer/puppeteer", "google-maps/google-maps"]
    query_params_list = [{"id": server_id, "config_name": "deepnlp_tool"} for server_id in server_ids]
    batch_tools_result = mcpm.list_tools_batch(query_params_list)
    print (f'DEBUG: list_tools_batch servers_ids {servers_ids}')
    print (f'DEBUG: list_tools_batch batch_tools_result {batch_tools_result}')

```



### 3. Load MCP Config 

Example 3.1 <code>load_config_batch</code> Method


```
    import mcp_marketplace as mcpm
    server_ids = ["puppeteer/puppeteer", "mendableai/firecrawl-mcp-server", "google-maps/google-maps"]
    mcp_config_result = mcpm.load_config_batch(server_ids, config_name="deepnlp_server")
    print (mcp_config_result)

```




### 4. Development Customized API and Endpoint

If you have MCP server APIs and want to customized the mcp_marketplace lib. You can pass the get_customized_url() function to the lib

The get_customized_url method assemble the endpoint and your id in a customized way and will post request to your Endpoint.

```
def customized_client():


    def get_customized_url(**param):
        id_value = param["id"] if "id" in param else ""
        base_url = param["endpoint"] if "endpoint" in param else ""
        return base_url + "/" + id_value
    
    mcpm.set_endpoint("http://www.deepnlp.org/api/mcp_marketplace/v1/tools")
    mcpm.get_customized_endpoint = get_customized_url
    
    ## **param: {"id": "puppeteer/puppeteer", "endpoint":"your_endpoint"}
    tools = mcpm.list_tools(id="puppeteer/puppeteer", endpoint=mcpm.endpoint)

```


### 5. Registry













## API Configuration

### Support Endpoint

| Endpoint | API |  Document  |
| ---- | ---- | ---- |
| http://www.deepnlp.org/api/mcp_marketplace/v1 | http://www.deepnlp.org/api/mcp_marketplace/v1?mode=list&query=map&page_id=0&count_per_page=100 | - |
| https://api.pulsemcp.com/v0beta/servers | https://api.pulsemcp.com/v0beta/servers?query=image&count_per_page=10 | https://www.pulsemcp.com/api |

### deepnlp.org


```

# list mode return paginated list
http://www.deepnlp.org/api/mcp_marketplace/v1?mode=list&query=map&page_id=0

http://www.deepnlp.org/api/mcp_marketplace/v1?mode=list&query=map&page_id=0&count_per_page=100

http://www.deepnlp.org/api/mcp_marketplace/v1?mode=list&query=map&offset=50&count_per_page=5


# dict mode return dict group by category

http://www.deepnlp.org/api/mcp_marketplace/v1?mode=dict&query=map&page_id=0

http://www.deepnlp.org/api/mcp_marketplace/v1?mode=dict&query=map&page_id=0&count_per_page=5

http://www.deepnlp.org/api/mcp_marketplace/v1?mode=dict&query=map&offset=50&count_per_page=5


# List Tools

http://www.deepnlp.org/api/mcp_marketplace/v1/tools/puppeteer/puppeteer

```


**Parameter**
| param | type | example |
| --- | ---- |  ---- | 
| mode |  string | "list", "dict", different use scenario |
| query |  string | e.g. query="Image" |
| page_id | integer | starting from 0 |
| count_per_page | integer |  5 |
| offset | integer | Optional, Equivalent to (page_id * count_per_page) e.g. 0 |



### pulsemcp.com

```
## query API
https://api.pulsemcp.com/v0beta/servers?query=image&count_per_page=10

## List API

https://api.pulsemcp.com/v0beta/servers
```

**Parameter**

| param | type | example |
| --- | ---- |  ---- | 
| query |  string | e.g. query="Image" |
| count_per_page | integer |  5 |
| offset | integer | Equivalent to (page_id * count_per_page) e.g. 0 |


### Related
- [MCP Marketplace DeepNLP](http://deepnlp.org/store/ai-agent/mcp-server)
- [MCP Marketplace PulseMCP](https://www.pulsemcp.com/)
- [Pypi](https://pypi.org/project/mcp-marketplace)
- [Github](https://github.com/aiagenta2z/mcp-marketplace)
- [AI Agent Marketplace](http://www.deepnlp.org/store/ai-agent)


