Paper2Agent tackles a persistent pain point in AI and research software development: turning sprawling, often inconsistent research paper codebases into usable, interactive tools for AI agents. It automates the entire process of scanning, running, and extracting tutorial notebooks from paper repositories, then wrapping the extracted tools into Model Context Protocol (MCP) servers that agents like Claude Code can use interactively. This pipeline can take hours and costs around $15 for complex repos, but it delivers a structured project with reusable tools, tests, and coverage reports — all with minimal manual effort.
what Paper2Agent does and its architecture
At its core, Paper2Agent is a multi-agent pipeline designed to reverse-engineer research paper codebases into production-ready MCP servers. It begins by scanning the supplied GitHub repository for tutorial notebooks, which are the primary entry points for understanding and running the research code. These notebooks are then executed in isolated environments to capture their outputs.
After execution, Paper2Agent extracts the reusable tools and functions embedded in these tutorials. These extracted tools are wrapped into an MCP server, which acts as an interface for AI coding agents such as Claude Code to invoke and interact with the functionalities programmatically.
The pipeline also generates test suites and coverage reports to assess the quality and completeness of the extracted tools. This automated testing is crucial since research codebases are often unstructured and lack formal tests.
The system supports both local and remote MCP server deployment, including hosting on platforms like Hugging Face Spaces. It also handles repositories requiring authentication via API keys and allows filtering to process only specific tutorials by title or URL.
Under the hood, Paper2Agent relies on Claude Code (an AI coding assistant) and the fastmcp framework for MCP server generation and interaction. The overall processing time depends heavily on the complexity of the codebase — ranging from 30 minutes for simpler repos to over 3 hours for large, complex projects like AlphaGenome.
The output is a well-organized project directory containing:
- The generated MCP server wrapping all extracted tools
- Isolated environments for running and testing
- Executed tutorial notebooks
- Test suites and coverage reports
This structure makes it easier for developers and AI agents to interact with research codebases in a standardized way.
technical strengths and tradeoffs
What sets Paper2Agent apart is its end-to-end automation of the often tedious manual process of understanding and repackaging research codebases. The pipeline’s ability to scan, execute, extract, and wrap tools into MCP servers with minimal human intervention is a significant time saver.
The codebase leverages the multi-agent pattern, where different components handle scanning, execution, extraction, and wrapping tasks. This modularity improves maintainability and makes the pipeline extensible to different research domains or notebook formats.
The integration with Claude Code as a backend AI assistant is a pragmatic choice, as it enables semantic understanding and interaction with code beyond simple parsing. Fastmcp provides a solid foundation for MCP server generation and communication.
However, the tradeoff lies in the processing time and cloud cost. Running complex repositories can take several hours and cost around $15, which might be prohibitive for casual users or quick experiments. The system also inherently depends on the quality and consistency of the original research notebooks; poorly documented or broken tutorials will impact the extraction quality.
The generated MCP servers and tests are only as good as the tutorials and code executed. So, despite automation, some manual review and refinement might be necessary for production use.
The code is surprisingly clean for a research automation tool, with clear separation of concerns across agents and pipeline stages. The README provides concrete usage examples and parameters, making it easier to integrate into existing workflows.
quick start with Paper2Agent
The project comes with a straightforward bash script to run the pipeline. Here’s the exact usage from the README:
cd Paper2Agent
bash Paper2Agent.sh \
--project_dir <PROJECT_DIR> \
--github_url <GITHUB_URL>
You can also target specific tutorials by title or URL:
bash Paper2Agent.sh \
--project_dir <PROJECT_DIR> \
--github_url <GITHUB_URL> \
--tutorials <TUTORIALS_URL or TUTORIALS_TITLE>
For private repositories requiring authentication:
bash Paper2Agent.sh \
--project_dir <PROJECT_DIR> \
--github_url <GITHUB_URL> \
--api <API_KEY>
Example usage for creating an AI agent from the TISSUE research paper codebase:
bash Paper2Agent.sh \
--project_dir TISSUE_Agent \
--github_url https://github.com/sunericd/TISSUE
These commands encapsulate the entire pipeline — from scanning the repo to generating the MCP server and tests.
who should consider using Paper2Agent
Paper2Agent is a solid fit for AI researchers, developers working with academic codebases, and teams aiming to build AI coding agents that can interact with research software dynamically. It automates a significant chunk of the grunt work involved in reverse-engineering tutorials and wrapping them into usable interfaces.
That said, it’s not a turn-key solution for all scenarios. The runtime and cloud cost are non-trivial, and the quality of results depends heavily on the source notebooks. Users should be prepared to invest time in reviewing and possibly extending the generated MCP servers and tests.
If you’re exploring how to operationalize research codebases for AI-assisted development or want to automate building interactive AI agents around new scientific tools, Paper2Agent provides a compelling starting point. The code quality and modular architecture make it accessible for further customization.
For less complex or smaller repos, the processing time and cost are manageable, making it useful for experimental projects. For large-scale or commercial applications, consider the tradeoffs around runtime and cost carefully.
Overall, Paper2Agent is a practical tool that addresses a specific niche with a clear architectural approach and honest tradeoffs.
→ GitHub Repo: jmiao24/Paper2Agent ⭐ 2,200 · Jupyter Notebook