{"type":"mcp_server","name":"serena","description":"Here are a few options, prioritizing clarity and SEO:\n\n*   **Option 1 (Focus on core function):** Semantic code retrieval & editing toolkit (MCP server). Agno integration.\n\n*   **Option 2 (More explic","category":"AI","language":"Python","stars":25885,"forks":285,"owner":"oraios","github_url":"https://github.com/oraios/serena","homepage":null,"setup":"## Setup\n\nSerena is managed by `uv`, so you will need to [install it](https://docs.astral.sh/uv/getting-started/installation/)).\n\n### Running the Serena MCP Server\n\nYou have several options for running the MCP server, which are explained in the subsections below.\n\n#### Usage\n\nThe typical usage involves the client (Claude Code, Claude Desktop, etc.) running\nthe MCP server as a subprocess (using stdio communication), \nso the client needs to be provided with the command to run the MCP server.\n(Alternatively, you can run the MCP server in SSE mode and tell your client \nhow to connect to it.)\n\nNote that no matter how you run the MCP server, Serena will, by default, start a small web-based dashboard on localhost that will display logs and allow shutting down the\nMCP server (since many clients fail to clean up processes correctly).\nThis and other settings can be adjusted in the [configuration](#configuration) and/or by providing [command-line arguments](#command-line-arguments).\n\n##### Local Installation\n\n1.  **Clone the repository:**\n    ```shell\n    git clone https://github.com/oraios/serena\n    cd serena\n    ```\n\n2.  **Optional: Create and configure the configuration file:**\n    Create the configuration file in your home directory:\n\n    *   `~/.serena/serena_config.yml` on Linux and macOS, or\n    *   `%USERPROFILE%\\.serena\\serena_config.yml` on Windows.\n\n    Copy the template and adjust it according to your needs:\n    ```shell\n    mkdir ~/.serena\n    cp src/serena/resources/serena_config.template.yml ~/.serena/serena_config.yml\n    ```\n    If you just want the default config, you can skip this part, and a config file will be created when you first run Serena.\n\n3.  **Run the server with `uv`:**\n    ```shell\n    uv run serena-mcp-server\n    ```\n    When running from outside the serena installation directory, be sure to pass it, i.e. use\n    ```shell\n     uv run --directory /abs/path/to/serena serena-mcp-server\n     ```\n\n##### Using uvx\n\n`uvx` can be used to run the latest version of Serena directly from the repository, without an explicit local installation.\n\n*   **Windows:**\n    ```shell\n    uvx --from git+https://github.com/oraios/serena serena-mcp-server.exe\n    ```\n*   **Other operating systems:**\n    ```shell\n    uvx --from git+https://github.com/oraios/serena serena-mcp-server\n    ```\n\n##### Using Docker (Experimental)\n\n⚠️ Docker support is currently experimental with several limitations. Please read the [Docker documentation](DOCKER.md) for important caveats before using it.\n\nYou can run the Serena MCP server directly via docker as follows,\nassuming that the projects you want to work on are all located in `/path/to/your/projects`:\n\n```shell\ndocker run --rm -i --network host -v /path/to/your/projects:/workspaces/projects ghcr.io/oraios/serena:latest serena-mcp-server --transport stdio\n```\n\nReplace `/path/to/your/projects` with the absolute path to your projects directory. The Docker approach provides:\n\n*   Better security isolation for shell command execution\n*   No need to install language servers and dependencies locally\n*   Consistent environment across different systems\n\nSee the [Docker documentation](DOCKER.md) for detailed setup instructions, configuration options, and known limitations.\n\n#### Prerequisites\n\n*   **uv:**  A Python package installer and resolver.  Install it following the instructions on [uv's documentation](https://docs.astral.sh/uv/getting-started/installation/).\n*   **Git:** Required for cloning the Serena repository.\n*   **Docker:** (Optional) Required if you choose to run Serena using Docker.\n*   **Language Servers:** For languages like Go, C#, Java, and Elixir, you may need to install the corresponding language server and dependencies separately. See the language support section in the main README for details.\n\n#### Configuration\n\nSerena's behavior (active tools and prompts as well as logging configuration, etc.) is configured in four places:\n\n1.  The `serena_config.yml` for general settings that apply to all clients and projects.\n    It is located in your user directory under `.serena/serena_config.yml`.\n    If you do not explicitly create the file, it will be auto-generated when you first run Serena.\n2.  In the arguments passed to the `serena-mcp-server` in your client's config (see below),\n    which will apply to all sessions started by the respective client. In particular, the [context](#contexts) parameter\n    should be set appropriately for Serena to be best adjusted to existing tools and capabilities of your client.\n    See for a detailed explanation. You can override all entries from the `serena_config.yml` through command line arguments.\n3.  In the `.serena/project.yml` file within your project. This will hold project-level configuration that is used whenever\n    that project is activated.\n4.  Through the currently active set of [modes](#modes).\n\n> ⚠️ **Note:** Serena is under active development. We are continuously adding features, improving stability and the UX.\n> As a result, configuration may change in a breaking manner. If you have an invalid configuration,\n> the MCP server or Serena-based Agent may fail to start (investigate the MCP logs in the former case).\n> Check the [changelog](CHANGELOG.md)\n> and the configuration templates when updating Serena, adapting your configurations accordingly.\n\nYou can just ask the LLM to show you the config of your session, Serena has a tool for it.\n\n#### Environment Variables\n\nSerena itself doesn't directly require environment variables for basic operation. However, depending on the LLM you integrate with (through Agno, for example), you might need to set API keys as environment variables.  Refer to the documentation of the specific LLM integration for details.  For example, if using Agno with OpenAI, you'll need to set `OPENAI_API_KEY`.","tools":"## Available Tools\n\nSerena provides a comprehensive set of tools designed to empower LLMs to interact with and modify codebases effectively. Here's a breakdown of each tool:\n\n*   `activate_project`: Activates a project by name. This tool is essential for setting the context for subsequent operations, ensuring that Serena operates within the correct codebase.\n    *   Usage Example: \"Activate the project my_project\"\n*   `check_onboarding_performed`: Checks whether project onboarding was already performed. Useful for determining if the initial project analysis has been completed.\n*   `create_text_file`: Creates/overwrites a file in the project directory. Allows the agent to generate new files or replace existing ones.\n*   `delete_lines`: Deletes a range of lines within a file. Enables precise removal of code sections.\n*   `delete_memory`: Deletes a memory from Serena's project-specific memory store. Useful for managing and cleaning up stored information.\n*   `execute_shell_command`: Executes a shell command. This is a powerful tool that allows the agent to run tests, build the project, or execute other commands necessary for development.\n*   `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced. Helps in understanding the usage of a particular code element.\n*   `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type). Similar to `find_referencing_code_snippets` but focuses on symbol references.\n*   `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type). Enables the agent to locate specific code elements within the project.\n    *   Usage Example: \"Find symbol 'my_function' in the current project.\"\n*   `get_active_project`: Gets the name of the currently active project (if any) and lists existing projects. Provides information about the current project context.\n*   `get_current_config`: Prints the current configuration of the agent, including the active modes, tools, and context. Useful for debugging and understanding the agent's current state.\n*   `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file or directory. Helps in understanding the structure of the code.\n*   `initial_instructions`: Gets the initial instructions for the current project. Should only be used in settings where the system prompt cannot be set, e.g. in clients you have no control over, like Claude Desktop.\n*   `insert_after_symbol`: Inserts content after the end of the definition of a given symbol. Allows for precise code insertion relative to existing symbols.\n*   `insert_at_line`: Inserts content at a given line in a file. Enables line-specific code insertion.\n*   `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol. Similar to `insert_after_symbol` but inserts before the symbol.\n*   `list_dir`: Lists files and directories in the given directory (optionally with recursion). Provides file system navigation capabilities.\n*   `list_memories`: Lists memories in Serena's project-specific memory store. Helps in managing stored information.\n*   `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building). Initializes the agent's understanding of the project.\n*   `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).\n*   `read_file`: Reads a file within the project directory. Allows the agent to access the contents of a file.\n*   `read_memory`: Reads the memory with the given name from Serena's project-specific memory store. Enables the agent to recall previously stored information.\n*   `replace_lines`: Replaces a range of lines within a file with new content. Allows for precise code replacement.\n*   `replace_symbol_body`: Replaces the full definition of a symbol. Enables complete replacement of a code element's implementation.\n*   `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.\n*   `search_for_pattern`: Performs a search for a pattern in the project. Allows for text-based searches within the codebase.\n*   `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.\n*   `switch_modes`: Activates modes by providing a list of their names. Enables dynamic adjustment of the agent's behavior.\n    *   Usage Example: \"Switch to planning and one-shot modes.\"\n*   `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.\n*   `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.\n*   `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.\n*   `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store. Allows the agent to store information for later use.","faq":null,"created_at":"2025-03-23T22:35:24+00:00","updated_at":"2025-07-07T16:44:48+00:00","source_url":"https://model-context-protocol.com/servers/serena","related_articles":[{"title":"serena MCP Server: AI Coding Agent for LLMs","url":"https://model-context-protocol.com/blog/serena-mcp-server-ai-coding-agent-for-llms-mcp-server-guide"}]}