Connected Serena Module

Connected Serena Module is an MCP server that provides AI assistants with access to the Serena software project management and development platform, enabling structured interactions with project workflows, code repositories, and team collaboration features. This MCP bridge allows language models to navigate project structures, review development artifacts, and assist with software engineering workflows through Serena's integrated development environment capabilities.

When to Use This MCP Server

Connect this server when...

• Your team uses Serena for software project management and you want AI-assisted access to project data and workflows
• You need conversational access to development artifacts including specifications, design documents, and code reviews
• You are coordinating software development tasks across teams and want AI help managing backlogs and sprint planning
• You want AI assistance analyzing project dependencies, timelines, and resource allocation within Serena
• Your workflow involves cross-referencing code changes with project requirements tracked in Serena

Consider alternatives when...

• Your project management is handled by Jira, Linear, or Asana, which have their own dedicated MCP servers
• You only need source control access without project management features
• Your team does not use Serena and has no plans to adopt it

Quick Start

Copy
# .mcp.json configuration
{
  "mcpServers": {
    "serena": {
      "command": "npx",
      "args": ["-y", "@serena/mcp-server"],
      "env": {
        "SERENA_API_KEY": "your-api-key",
        "SERENA_WORKSPACE": "your-workspace-id"
      }
    }
  }
}

Connection setup:

1. Obtain API credentials from your Serena workspace administrator
2. Locate your workspace ID from the Serena settings page
3. Add the configuration above to your .mcp.json file with your credentials
4. Restart your MCP client to establish the connection

Example tool usage:

# Browse project structure
> Show me all active projects in the workspace and their current sprint status

# Review development items
> List the open tasks assigned to me in the current sprint

# Analyze project health
> What is the velocity trend for the backend team over the last 5 sprints?

Core Concepts

Concept	Purpose	Details
Workspaces	Organizational scope	Top-level containers that group projects, teams, and configuration for an organization or division
Projects	Development units	Individual software projects containing backlogs, sprints, milestones, and associated repositories
Sprints	Time-boxed iterations	Fixed-duration development cycles with planned work items, velocity tracking, and burndown metrics
Artifacts	Development deliverables	Specifications, design documents, code reviews, and other structured documents within projects
Workflows	Process automation	Configurable state machines that govern how work items progress through stages from creation to completion

Architecture:

+------------------+       +------------------+       +------------------+
|  Serena          |       |  Serena MCP      |       |  AI Assistant    |
|  Platform        |<----->|  Server (npx)    |<----->|  (Claude, etc.)  |
|  REST API        | HTTPS |  stdio transport  | stdio |                  |
+------------------+       +------------------+       +------------------+
        |
        v
+--------------------------------------------------+
|  Workspaces > Projects > Sprints > Items > Docs   |
+--------------------------------------------------+

Configuration

Parameter	Type	Default	Description
SERENA_API_KEY	string	(required)	API key for authenticating with the Serena platform
SERENA_WORKSPACE	string	(required)	Workspace identifier scoping all operations to your organization
default_project	string	none	Default project ID for operations when not explicitly specified
include_archived	boolean	false	Whether to include archived sprints and items in query results
page_size	integer	50	Number of items returned per page for list operations

Best Practices

1. Scope queries to specific projects for performance. Workspaces can contain dozens of projects with thousands of work items. Always specify the project when querying items, sprints, or artifacts to get focused results and reduce API load on the Serena platform.

2. Use sprint context for time-relevant queries. When asking about current work, specify the active sprint to filter out completed and future items. This gives the AI a focused view of what is actively being worked on and what needs attention before the sprint ends.

3. Leverage workflow metadata for status tracking. Serena's configurable workflows carry rich state information beyond simple "open" and "closed" statuses. Ask the AI to consider workflow stages like "in review", "blocked", and "ready for deployment" for nuanced project health assessments.

4. Cross-reference artifacts with code changes. Use the MCP server to link Serena work items with corresponding code changes. This traceability helps the AI provide context-aware code reviews by understanding the requirements and design decisions behind implementation choices.

5. Archive completed sprints rather than deleting them. Maintain historical sprint data for velocity tracking and retrospective analysis. Archived sprints remain queryable when the include_archived flag is enabled, providing valuable trend data for project planning.

Common Issues

"Workspace not found" when connecting. Verify that the SERENA_WORKSPACE value matches the workspace ID shown in your Serena settings, not the display name. Workspace IDs are typically alphanumeric strings. Contact your workspace administrator if you cannot locate the correct identifier.

API key authentication fails. Ensure the API key has the necessary permissions for the operations you are performing. Some Serena configurations require separate read and write API keys. Verify the key has not been revoked by checking the API keys section in your Serena workspace settings.

Sprint data appears incomplete or missing. Check whether the sprints you are querying have been archived. By default, only active sprints are returned. Enable the include_archived flag if you need historical sprint data. Also verify that the project has sprints configured, as some projects may use a Kanban workflow without sprint boundaries.