Let Gradio apps also be MCP Servers

[abidlabs]

Gradio apps are also now MCP Servers. TLDR: to use, just add mcp_server=True in .launch()

This works for Gradio apps running locally as well as hosted Gradio apps on Spaces. Keep reading on how to test this PR...

Testing MCP Server Running on Spaces

To make this easy to test, I've launched two Gradio apps on Spaces using this PR that you can use to test:

• https://huggingface.co/spaces/abidlabs/mcp-tools: includes 4 tools of different kinds of modalities (text-in-text-out, image-in-text-out, text-in-image-out, image-in-image-out). All the tools run very quickly, making it easy for testing.
• https://huggingface.co/spaces/abidlabs/EasyGhibli: includes a single tool that converts images to ghlibli style images. Inference time is about 10 seconds, so use for more occasional testing.

Testing MCP Server Running Locally

To test this out locally, first install gradio from this PR following the instructions below. Also install mcp e.g. pip install mcp

Then, launch a Gradio app like this:

import gradio as gr

def letter_counter(word, letter):
    """
    Count the number of occurrences of a letter in a word or text.

    Args:
        word (str): The input text to search through
        letter (str): The letter to search for

    Returns:
        str: A message indicating how many times the letter appears
    """
    word = word.lower()
    letter = letter.lower()
    count = word.count(letter)    
    return count

# Create and launch the Gradio interface
demo = gr.Interface(
    fn=letter_counter,
    inputs=["textbox", "textbox"],
    outputs="number",
    title="Letter Counter",
    description="Enter text and a letter to count how many times the letter appears in the text."
)

if __name__ == "__main__":
    demo.launch(mcp_server=True) # Alternatively use the GRADIO_MCP_SERVER env variable

Note the .launch(mcp_server=True).

Once you launch the Gradio app, the "view API" page should include a 4th "language" option called MCP. There will also be a code box that shows that configuration that you need to paste inside your MCP Client (e.g. Cline).

Note that since this uses SSE protocol, this will work for any client that supports that such as Cline or Cursor. I've also added instructions for integrating with clients like Claude Desktop that do not

You can also test with the MCP Inspector, which is a fantastic debugging tool.

Once you post the config json in e.g. Cline, you should be able to ask a question like: "how many rs in strawberry" and the model should respond like this:

Closes: #10949

[gradio-pr-bot]

🪼 branch checks and previews

•	Name	Status	URL
	Spaces	ready!	Spaces preview
	Website	building...
	Storybook	ready!	Storybook preview
🦄	Changes	detected!	Details

---

Install Gradio from this PR

pip install https://gradio-pypi-previews.s3.amazonaws.com/37eed343820421df566b8aaec4210c92b60e2087/gradio-5.27.1-py3-none-any.whl

Install Gradio Python Client from this PR

pip install "gradio-client @ git+https://github.com/gradio-app/gradio@37eed343820421df566b8aaec4210c92b60e2087#subdirectory=client/python"

Install Gradio JS Client from this PR

npm install https://gradio-npm-previews.s3.amazonaws.com/37eed343820421df566b8aaec4210c92b60e2087/gradio-client-1.14.2.tgz

Use Lite from this PR

<script type="module" src="https://gradio-lite-previews.s3.amazonaws.com/37eed343820421df566b8aaec4210c92b60e2087/dist/lite.js""></script>

[gradio-pr-bot]

🦄 change detected

This Pull Request includes changes to the following packages.

Package	Version
@gradio/core	minor
gradio	minor
gradio_client	minor

• Maintainers can select this checkbox to manually select packages to update.

With the following changelog entry.

Let Gradio apps also be MCP Servers

Maintainers or the PR author can modify the PR title to modify this entry.

Something isn't right?

• Maintainers can change the version label to modify the version bump.
• If the bot has failed to detect any changes, or if this pull request needs to update multiple packages to different versions or requires a more comprehensive changelog entry, maintainers can update the changelog file directly.

[freddyaboulton]

Nice!

[freddyaboulton]

Tool description shows undefined if the parameter does not have a description in the docstring. We should be showing the same info in /schema, no?

[freddyaboulton]

We should use the space-id here if available so that mcp serves have unique names for spaces.

[freddyaboulton]

There is an issue when using multiple gradio apps as mcp servers at the same time in cursor.

I had two active gradio mcp sessions, one was a dummy audio reversal interface, and the other was a dummy audio transcription server. I gave each server a unique name but each had one tool called predict.

When I told it to transcribe audio, it kept using the predict function from the dummy audio reversal interface instead of the audio transcription server. Even after I prompted it to use the correct mcp server! Only after disabling the other mcp server did it work.

This is an app issue instead of a server issue (we should file an issue with cursor?), but should we give our tools unique names (perhaps by prepending with the space id when available) to maximize the chance of gradio mcp servers "just working"?

[freddyaboulton]

Here are screenshots of the interaction:

Here I manually disabled the other gradio mcp server

[abidlabs]

Everything should be addressed now @freddyaboulton! MCP tool names now include a prefix if running on Spaces:

[freddyaboulton]

Awesome PR! Left some questions mainly on the code in the new guide. Functionality is great. let's ship ✅

[freddyaboulton]

What's the benefit of using AsyncExitStack over just using ClientSession and stdio_client in an async with ?

[abidlabs]

Not sure, will leave it to @yvrjsharma to make the change if needed

[freddyaboulton]

I think connect can be async if it's just just used in the connect button click event.

[freddyaboulton]

I think it would be clearer if everything was async rather than mixing sync and async scopes via loop.run_until_complete. Anthropic has an async client so I think it's possible just to make everything async.

[abidlabs]

Switched over the MCP Client Guide to use the Gradio Python Client. I don't have the full context for the other changes, so I think it's fine to leave as is until @yvrjsharma is back!

[abidlabs]

Thanks so much for the reviews and contributions @freddyaboulton @yvrjsharma @evalstate @cocktailpeanut!