Reflex MCP Chat App

A starting point for a highly customizable Python web application that uses LLMs with access to MCP (Model context protocol) servers to build a highly capable chat application. (Please leave a ⭐ if you like it!)

The interface is based on the Reflex chat app template.

The inner workings are completely new, utilizing the latest approaches to LLM application development with LangGraph and MCP (Model Context Protocol).

demo.webm

Key Technologies Used

• Reflex - A Python web framework for building interactive web applications.
• LangGraph - A framework for building LLM applications
• MCP - Anthropics open source protocol for providing context to LLM applications.
  • Example integrations with:
    • GitHubMCP
    • Git
    • Filesystem
    • Minimal example SSE
• UV - An extremely fast Python project manager.
• Taskfile - A task runner for automating common tasks in the development process.
• GitHubActions - GitHub's automation tool for CI/CD.
• Pyright - A static type checker for Python.
• Ruff - A fast Python linter and code formatter.
• Pre-commit - A framework for managing and maintaining multi-language pre-commit hooks.
• Pytest - A testing framework for Python.
• Dependency Injector - A dependency injection framework for python that allow for easy management of app configuration and testing.

---

Getting Started

🧬 1. Clone the Repo

git clone https://github.com/TimChild/reflex-mcp-chat.git

📦 2. Install UV

If you don't already have uv installed, you can follow the instructions here.

For macOS, linux, and wsl2

curl -LsSf https://astral.sh/uv/install.sh | sh

🛠️ 3. (Optionally) Install Taskfile

I recommend installing Taskfile to make it easier to run tasks in the project, but you can also run any necessary commands manually (using the Taskfile.yml as a reference).

On linux (Debian/Ubuntu):

sudo snap install task --classic

On macOS:

brew install go-task/tap/go-task

⚙️ 4. Setup

Create a .env file (or add directly to environment vars):

• OPENAI_API_KEY -- https://platform.openai.com/settings/
• ANTHROPIC_API_KEY -- https://console.anthropic.com/settings/keys
• GITHUB_PERSONAL_ACCESS_TOKEN -- https://github.com/settings/personal-access-tokens/new

[!TIP] You can copy the .env.template file to .env and fill in the values there. You can also set any non-empty string if you don't want to use that feature (the app checks that they are not-null for easier debugging).

You can also modify the config.yml file to add/remove MCP servers and change other app behavior.

Currently the config is set to allow the MCP file server to make changes in ~/mcp_allowed (you'll need to create that directory first).

🚀 5. Run the application

task run

Then open localhost:3000 in your browser.

App Features

• 100% Python-based, including the UI, using Reflex
• Selectable LLMs (OpenAI and Anthropic implemented, easily extendable) -- Dropdown selection in the UI
• Runs via LangGraph's standard Graph mode or new Functional API -- Dropdown selection in the UI (note: implemented behavior is identical -- allows you to extend either method)
• Custom MCP client for easy management of multiple MCP servers
• Multiple MCP severs included via 4 different modes for easy extension. Examples include:
  • http SSE (Server-Sent Events)
  • local python stdio via uv
  • docker container
  • stdio from github repo via npx
• The application is fully customizable without typical frontend development experience.
  • See https://reflex.dev/docs/getting-started/introduction/
• Responsive design for various devices

Development Environment

There are many helpful tasks to help with development:

Then, to set up all development dependencies

task install

To run type checking, linting, and testing:

task test

To run tests on any changes:

task watch-tests

To run a jupyter lab with all dependencies:

task jupyter

CI/CD workflows are included for automated testing and deployment. Find them in the .github/workflows directory.

Uses Dependency Injector for easy management of app configuration and testing.

App configuration is managed via a config.yml file and containers.py file.

TODOs:

A few things that could improve the app:

• Add a mkdocs site
• Add docker/docker-compose support
• Add deployment workflow template
• Add end-to-end tests using playwright
• Add postgres persistence (partially implemented)
• Better handling of long conversations
• Better handling of large content returned from tools
• Add MCP resource and prompt support
• Add MCP sampling support

Contributing

If you'd like to contribute, please do the following:

• Fork the repository and make your changes.
• Once you're ready, submit a pull request for review.

License

The following repo is licensed under the MIT License.